@beeos-ai/cli 1.0.24 → 1.1.1

package/dist/index.js

@@ -1245,6 +1245,18 @@ var init_upgrade = __esm({
 });
 
 // ../core/dist/device-setup.js
+function inferHostBackend() {
+  switch (process.platform) {
+    case "darwin":
+      return "macos";
+    case "linux":
+      return "linux";
+    case "win32":
+      return "windows";
+    default:
+      return null;
+  }
+}
 function agentBinCommandAndArgs(bin) {
   if (bin.type === "executable") {
     return { cmd: bin.path, args: [] };
@@ -1746,6 +1758,8 @@ function cargoDistTarget() {
     case "win32":
       if (arch === "x64")
         return "x86_64-pc-windows-msvc";
+      if (arch === "arm64")
+        return "aarch64-pc-windows-msvc";
       return null;
     default:
       return null;
@@ -2335,6 +2349,9 @@ function hasStartupDiagnostics(driver) {
 function hasPreflightConflictCheck(driver) {
   return typeof driver.preflightConflictCheck === "function";
 }
+function hasDesktopCapability(driver) {
+  return typeof driver.desktopBridgeSpec === "function";
+}
 var init_driver = __esm({
   "../core/dist/agent/driver.js"() {
     "use strict";
@@ -2721,6 +2738,35 @@ var init_wait_for_healthcheck = __esm({
   }
 });
 
+// ../core/dist/services/target-spec.js
+function buildVncBridgeTargetSpec(binary, opts) {
+  return {
+    id: `vnc-bridge-${opts.serial}`,
+    kind: "vnc-bridge",
+    command: binary,
+    args: [],
+    env: vncBridgeRuntime.buildEnv(opts),
+    restart: "on-failure",
+    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";
+  }
+});
+
 // ../core/dist/openclaw/config.js
 import { sha256 as sha2562 } from "@noble/hashes/sha256";
 import { bytesToHex as bytesToHex2 } from "@noble/hashes/utils";
@@ -3153,6 +3199,8 @@ var init_driver2 = __esm({
     init_platform_adapter();
     init_paths();
     init_detector();
+    init_vnc_bridge();
+    init_target_spec();
     init_constants();
     init_config();
     init_detect_local();
@@ -3251,6 +3299,56 @@ var init_driver2 = __esm({
             return { state: "unknown", reason: `unhandled probe state` };
         }
       }
+      /**
+       * Multi-OS refactor Phase 0: previously `start.ts` knew the
+       * vnc-bridge wiring directly (binary path lookup, env-var shape,
+       * `bridgePrivateKeyFile`/`bridgePublicKeyFile` reusing OpenClaw's
+       * keypair). That coupling broke the "framework axis ⊥ desktop
+       * axis" promise — adding e.g. Hermes-with-desktop required
+       * copying the same boilerplate in `start.ts` for each new
+       * framework. The driver now owns the bridge wiring; `start.ts`
+       * just calls `desktopBridgeSpec()` and folds the outcome into
+       * its existing `launchWarnings` stream.
+       *
+       * Soft-failure contract: any path that today produced a
+       * `launchWarnings` entry in `tryAttachOpenclawDesktopBridge`
+       * (binary unavailable, download failed, install threw) returns
+       * `{ spec: null, warnings: [...] }` here instead of throwing.
+       * The caller MUST NOT abort the bind on a `null` spec — desktop
+       * streaming is bonus on top of an already-bound OpenClaw.
+       */
+      async desktopBridgeSpec(endpoint, ctx, reporter) {
+        let binary;
+        try {
+          binary = await vncBridgeRuntime.ensureInstalled(reporter);
+        } catch (e) {
+          const reason = e instanceof Error ? e.message : String(e);
+          return {
+            spec: null,
+            warnings: [
+              `vnc-bridge install failed: ${reason}; OpenClaw is bound but desktop streaming is unavailable.`
+            ]
+          };
+        }
+        if (!binary) {
+          return {
+            spec: null,
+            warnings: [
+              `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: ctx.instanceId,
+          vncHost: endpoint.host,
+          vncPort: endpoint.port,
+          ...ctx.vncPassword ? { vncPassword: ctx.vncPassword } : {},
+          agentGatewayUrl: ctx.agentGatewayUrl,
+          bridgePrivateKeyFile: ctx.keyFile,
+          bridgePublicKeyFile: ctx.keyFile
+        });
+        return { spec, warnings: [] };
+      }
     };
     openClawDriver = new OpenclawDriver();
   }
@@ -3273,10 +3371,6 @@ 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];
 }
@@ -3344,6 +3438,75 @@ var init_desktop_detect = __esm({
   }
 });
 
+// ../core/dist/desktop/platforms/common.js
+import { createCipheriv } from "crypto";
+async function readVncPasswordFromBeeoHome() {
+  const env = process.env.BEEOS_VNC_PASSWORD?.trim();
+  if (env)
+    return env;
+  const p = getPlatformAdapter();
+  const file = p.joinPath(beeoHome(), "vnc.password");
+  try {
+    const raw = (await p.readFile(file)).trim();
+    return raw || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function generateLegacyVncPassword() {
+  const out = new Array(VNC_PASSWORD_LENGTH);
+  const buf = new Uint8Array(VNC_PASSWORD_LENGTH);
+  globalThis.crypto.getRandomValues(buf);
+  for (let i = 0; i < VNC_PASSWORD_LENGTH; i++) {
+    out[i] = VNC_PASSWORD_CHARSET[buf[i] % VNC_PASSWORD_CHARSET.length];
+  }
+  return out.join("");
+}
+function isShellSafeVncPassword(p) {
+  return /^[a-zA-Z0-9]{8}$/.test(p);
+}
+function encodeVncPasswordBytes(plaintext) {
+  const padded = Buffer.alloc(8);
+  Buffer.from(plaintext, "utf8").copy(padded, 0, 0, Math.min(plaintext.length, 8));
+  const key = Buffer.alloc(8);
+  for (let i = 0; i < 8; i++) {
+    key[i] = reverseBits(padded[i]);
+  }
+  const challenge = Buffer.from([
+    23,
+    82,
+    107,
+    6,
+    35,
+    78,
+    88,
+    7
+  ]);
+  const tripleKey = Buffer.concat([key, key, key]);
+  const cipher = createCipheriv("des-ede3-ecb", tripleKey, null);
+  cipher.setAutoPadding(false);
+  return Buffer.concat([cipher.update(challenge), cipher.final()]);
+}
+function reverseBits(b) {
+  let r = 0;
+  let v = b & 255;
+  for (let i = 0; i < 8; i++) {
+    r = r << 1 | v & 1;
+    v >>= 1;
+  }
+  return r & 255;
+}
+var VNC_PASSWORD_LENGTH, VNC_PASSWORD_CHARSET;
+var init_common = __esm({
+  "../core/dist/desktop/platforms/common.js"() {
+    "use strict";
+    init_platform_adapter();
+    init_paths();
+    VNC_PASSWORD_LENGTH = 8;
+    VNC_PASSWORD_CHARSET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  }
+});
+
 // ../core/dist/openclaw/macos-desktop-cold-start.js
 async function detectColdStartState() {
   const p = getPlatformAdapter();
@@ -3456,15 +3619,6 @@ async function ensureBeeoHome(p) {
     await p.mkdir(home);
   }
 }
-function generateLegacyVncPassword() {
-  const out = new Array(VNC_PASSWORD_LENGTH);
-  const buf = new Uint8Array(VNC_PASSWORD_LENGTH);
-  globalThis.crypto.getRandomValues(buf);
-  for (let i = 0; i < VNC_PASSWORD_LENGTH; i++) {
-    out[i] = VNC_PASSWORD_CHARSET[buf[i] % VNC_PASSWORD_CHARSET.length];
-  }
-  return out.join("");
-}
 function encodeMacosVncPassword(password) {
   const pwBytes = Buffer.alloc(APPLE_VNC_FIXED_KEY.length);
   Buffer.from(password, "utf8").copy(pwBytes);
@@ -3540,15 +3694,14 @@ async function probeArdAllLocalUsers() {
 function sleep3(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-var APPLE_VNC_FIXED_KEY, VNC_PASSWORD_LENGTH, VNC_PASSWORD_CHARSET, ARD_PLIST_PATH, VNC_SETTINGS_PATH, PORT_5900_PROBE_TIMEOUT_MS, VERIFY_5900_TIMEOUT_MS, VERIFY_5900_POLL_INTERVAL_MS, OSASCRIPT_TIMEOUT_MS;
+var APPLE_VNC_FIXED_KEY, ARD_PLIST_PATH, VNC_SETTINGS_PATH, PORT_5900_PROBE_TIMEOUT_MS, VERIFY_5900_TIMEOUT_MS, VERIFY_5900_POLL_INTERVAL_MS, OSASCRIPT_TIMEOUT_MS;
 var init_macos_desktop_cold_start = __esm({
   "../core/dist/openclaw/macos-desktop-cold-start.js"() {
     "use strict";
     init_platform_adapter();
     init_paths();
+    init_common();
     APPLE_VNC_FIXED_KEY = Buffer.from("1734516E8BA8C5E2FF1C39567390ADCA", "hex");
-    VNC_PASSWORD_LENGTH = 8;
-    VNC_PASSWORD_CHARSET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
     ARD_PLIST_PATH = "/Library/Preferences/com.apple.RemoteManagement.plist";
     VNC_SETTINGS_PATH = "/Library/Preferences/com.apple.VNCSettings.txt";
     PORT_5900_PROBE_TIMEOUT_MS = 200;
@@ -3558,6 +3711,655 @@ var init_macos_desktop_cold_start = __esm({
   }
 });
 
+// ../core/dist/desktop/pipeline.js
+var DesktopPipeline;
+var init_pipeline = __esm({
+  "../core/dist/desktop/pipeline.js"() {
+    "use strict";
+    DesktopPipeline = class {
+      platform;
+      constructor(platform) {
+        this.platform = platform;
+      }
+      /** Stable platform tag — proxied from the underlying adapter. */
+      get id() {
+        return this.platform.id;
+      }
+      coldStart(opts) {
+        return this.platform.coldStart(opts);
+      }
+      probe(opts) {
+        return this.platform.probe(opts);
+      }
+      readPasswordOptional() {
+        return this.platform.readPasswordOptional();
+      }
+      postSetupHint(endpoint) {
+        return this.platform.postSetupHint(endpoint);
+      }
+    };
+  }
+});
+
+// ../core/dist/desktop/platforms/macos.js
+var MacosDesktopPlatform, macosDesktopPlatform;
+var init_macos = __esm({
+  "../core/dist/desktop/platforms/macos.js"() {
+    "use strict";
+    init_desktop_detect();
+    init_macos_desktop_cold_start();
+    init_common();
+    MacosDesktopPlatform = class {
+      id = "macos";
+      coldStart(opts) {
+        return macosDesktopColdStart(opts);
+      }
+      probe(opts) {
+        return probeLocalVnc(opts);
+      }
+      readPasswordOptional() {
+        return readVncPasswordFromBeeoHome();
+      }
+      postSetupHint(endpoint) {
+        if (endpoint.kind !== "macos")
+          return [];
+        return MACOS_DESKTOP_HINT_LINES;
+      }
+    };
+    macosDesktopPlatform = new MacosDesktopPlatform();
+  }
+});
+
+// ../core/dist/desktop/platforms/linux.js
+async function ensureBeeoHome2() {
+  const p = getPlatformAdapter();
+  const home = beeoHome();
+  if (!await p.exists(home)) {
+    await p.mkdir(home);
+  }
+}
+async function detectLinuxColdStartState() {
+  const p = getPlatformAdapter();
+  const port5901Listening = await p.tcpProbe("127.0.0.1", LINUX_VNC_PORT, PORT_PROBE_TIMEOUT_MS).catch(() => false);
+  const beeoFile = p.joinPath(beeoHome(), "vnc.password");
+  let beeoPasswordFileExists = false;
+  try {
+    const raw = await p.readFile(beeoFile);
+    beeoPasswordFileExists = raw.trim().length > 0;
+  } catch {
+    beeoPasswordFileExists = false;
+  }
+  const systemFile = p.joinPath(p.homeDir(), ".vnc", "passwd");
+  let systemPasswordFileExists = false;
+  try {
+    const raw = await p.readFile(systemFile);
+    systemPasswordFileExists = raw.length > 0;
+  } catch {
+    systemPasswordFileExists = false;
+  }
+  const passwdToolPath = await firstOnPath(VNCPASSWD_CANDIDATES);
+  const vncServerPath = await firstOnPath(VNCSERVER_CANDIDATES);
+  return {
+    port5901Listening,
+    beeoPasswordFileExists,
+    systemPasswordFileExists,
+    passwdToolPath,
+    vncServerPath
+  };
+}
+async function firstOnPath(candidates) {
+  const p = getPlatformAdapter();
+  for (const name of candidates) {
+    try {
+      const result = await p.exec("which", [name]);
+      if (result.code === 0 && result.stdout.trim()) {
+        return result.stdout.trim().split("\n")[0].trim();
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+async function writeSystemVncPasswd(toolPath, password) {
+  if (!isShellSafeVncPassword(password)) {
+    return {
+      ok: false,
+      detail: "internal: refusing to pipe shell-unsafe password into tigervncpasswd"
+    };
+  }
+  const p = getPlatformAdapter();
+  const home = p.homeDir();
+  const vncDir = p.joinPath(home, ".vnc");
+  const target = p.joinPath(vncDir, "passwd");
+  if (!await p.exists(vncDir)) {
+    try {
+      await p.mkdir(vncDir);
+    } catch (e) {
+      return { ok: false, detail: `mkdir ${vncDir}: ${describeError3(e)}` };
+    }
+  }
+  const shellCmd = `printf '%s' '${password}' | '${toolPath}' -f > '${target}' && chmod 0600 '${target}'`;
+  try {
+    const result = await p.exec("sh", ["-c", shellCmd], {
+      timeout: VNCPASSWD_TIMEOUT_MS
+    });
+    if (result.code !== 0) {
+      return {
+        ok: false,
+        detail: result.stderr.trim() || `exit ${result.code}`
+      };
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, detail: describeError3(e) };
+  }
+}
+async function startVncServer(vncServerPath) {
+  const p = getPlatformAdapter();
+  try {
+    const result = await p.exec(vncServerPath, [
+      LINUX_VNC_DISPLAY,
+      "-localhost",
+      "yes",
+      "-SecurityTypes",
+      "VncAuth"
+    ], { timeout: VNCSERVER_TIMEOUT_MS });
+    if (result.code !== 0) {
+      return {
+        ok: false,
+        detail: (result.stderr || result.stdout).trim() || `exit ${result.code}`
+      };
+    }
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, detail: describeError3(e) };
+  }
+}
+async function waitForPort(port, timeoutMs) {
+  const p = getPlatformAdapter();
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await p.tcpProbe("127.0.0.1", port, PORT_PROBE_TIMEOUT_MS).catch(() => false)) {
+      return true;
+    }
+    await sleep4(VERIFY_POLL_INTERVAL_MS);
+  }
+  return false;
+}
+function sleep4(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function describeError3(e) {
+  if (e instanceof Error) {
+    const msg = e.message.split(/\r?\n/, 1)[0]?.trim();
+    return msg && msg.length > 0 ? msg : e.name;
+  }
+  return String(e);
+}
+var LINUX_VNC_PORT, LINUX_VNC_DISPLAY, PORT_PROBE_TIMEOUT_MS, VERIFY_TIMEOUT_MS, VERIFY_POLL_INTERVAL_MS, VNCSERVER_TIMEOUT_MS, VNCPASSWD_TIMEOUT_MS, VNCPASSWD_CANDIDATES, VNCSERVER_CANDIDATES, LinuxDesktopPlatform, linuxDesktopPlatform;
+var init_linux = __esm({
+  "../core/dist/desktop/platforms/linux.js"() {
+    "use strict";
+    init_desktop_detect();
+    init_platform_adapter();
+    init_paths();
+    init_common();
+    LINUX_VNC_PORT = 5901;
+    LINUX_VNC_DISPLAY = ":1";
+    PORT_PROBE_TIMEOUT_MS = 200;
+    VERIFY_TIMEOUT_MS = 8e3;
+    VERIFY_POLL_INTERVAL_MS = 250;
+    VNCSERVER_TIMEOUT_MS = 3e4;
+    VNCPASSWD_TIMEOUT_MS = 5e3;
+    VNCPASSWD_CANDIDATES = [
+      "tigervncpasswd",
+      "vncpasswd"
+    ];
+    VNCSERVER_CANDIDATES = ["vncserver"];
+    LinuxDesktopPlatform = class {
+      id = "linux";
+      async coldStart(opts) {
+        if (opts.noDesktop)
+          return { status: "skipped_opt_out" };
+        const log = opts.log ?? ((m) => console.log(m));
+        const p = getPlatformAdapter();
+        const state = await detectLinuxColdStartState();
+        if (state.passwdToolPath === null) {
+          return { status: "skipped_no_vnc_server" };
+        }
+        const beeoPasswordFile = p.joinPath(beeoHome(), "vnc.password");
+        if (state.port5901Listening && state.beeoPasswordFileExists && state.systemPasswordFileExists) {
+          let existing;
+          try {
+            existing = (await p.readFile(beeoPasswordFile)).trim() || void 0;
+          } catch {
+            existing = void 0;
+          }
+          return { status: "already_configured", vncPassword: existing };
+        }
+        if (!opts.prompt && !opts.yes) {
+          return { status: "skipped_no_tty" };
+        }
+        if (!opts.yes) {
+          log("");
+          log("BeeOS desktop streaming needs a local VNC server with a known password.");
+          log("This will:");
+          log("  - Generate an 8-char VNC viewer password");
+          log("  - Write it to ~/.vnc/passwd (chmod 600) using `tigervncpasswd -f`");
+          log("  - Mirror the same plaintext into ~/.beeos/vnc.password");
+          log(`  - Start \`vncserver ${LINUX_VNC_DISPLAY} -localhost yes\` if it isn't already running`);
+          log("If you already use ~/.vnc/passwd for other tools the existing");
+          log("password will be REPLACED. No sudo, no package install \u2014 only");
+          log("files inside your home directory are modified.");
+          log("");
+          const answer = (await opts.prompt("Configure VNC password and start vncserver for desktop streaming? [Y/n]: ")).trim();
+          if (answer !== "" && !/^y(es)?$/i.test(answer)) {
+            return { status: "user_declined" };
+          }
+        }
+        const newPassword = generateLegacyVncPassword();
+        if (!isShellSafeVncPassword(newPassword)) {
+          return {
+            status: "script_failed",
+            warnings: [
+              "linux cold-start: generated VNC password contained shell-unsafe characters; refusing to invoke `tigervncpasswd -f` via shell pipe. Re-run `beeos init`."
+            ]
+          };
+        }
+        try {
+          await ensureBeeoHome2();
+          await p.writeFile(beeoPasswordFile, newPassword);
+          await p.chmod(beeoPasswordFile, 384);
+        } catch (e) {
+          return {
+            status: "script_failed",
+            warnings: [
+              `linux cold-start: failed to write ${beeoPasswordFile}: ${describeError3(e)}. Desktop streaming will not work this run.`
+            ]
+          };
+        }
+        const passwdResult = await writeSystemVncPasswd(state.passwdToolPath, newPassword);
+        if (!passwdResult.ok) {
+          await p.rm(beeoPasswordFile).catch(() => void 0);
+          return {
+            status: "script_failed",
+            warnings: [
+              `linux cold-start: \`${state.passwdToolPath} -f\` failed: ${passwdResult.detail}. Desktop streaming will not work this run.`
+            ]
+          };
+        }
+        if (!state.port5901Listening) {
+          if (state.vncServerPath === null) {
+            return {
+              status: "verify_timeout",
+              warnings: [
+                `linux cold-start: password files written but \`vncserver\` is not on PATH \u2014 start it manually with \`vncserver ${LINUX_VNC_DISPLAY} -localhost yes -SecurityTypes VncAuth\` and re-run \`beeos init\`.`
+              ]
+            };
+          }
+          const startResult = await startVncServer(state.vncServerPath);
+          if (!startResult.ok) {
+            return {
+              status: "script_failed",
+              warnings: [
+                `linux cold-start: \`vncserver ${LINUX_VNC_DISPLAY}\` failed: ${startResult.detail}. Check ~/.vnc/<host>:1.log for startup errors.`
+              ]
+            };
+          }
+        }
+        const up = await waitForPort(LINUX_VNC_PORT, VERIFY_TIMEOUT_MS);
+        if (!up) {
+          return {
+            status: "verify_timeout",
+            warnings: [
+              `linux cold-start ran but :${LINUX_VNC_PORT} never came up within 8s. Check \`~/.vnc/$HOSTNAME${LINUX_VNC_DISPLAY}.log\` or run \`beeos doctor\`.`
+            ]
+          };
+        }
+        log(`vncserver ${LINUX_VNC_DISPLAY} is listening on :${LINUX_VNC_PORT} (loopback only).`);
+        return { status: "enabled_now", vncPassword: newPassword };
+      }
+      probe(opts) {
+        return probeLocalVnc(opts);
+      }
+      readPasswordOptional() {
+        return readVncPasswordFromBeeoHome();
+      }
+      postSetupHint(_endpoint) {
+        return [
+          "Linux desktop streaming notes:",
+          "  \u2022 vncserver is listening on 127.0.0.1:5901 only \u2014 exposing it externally requires",
+          "    explicit firewall + auth setup (out of scope for the BeeOS install).",
+          "  \u2022 Headless setups need an X session: edit ~/.vnc/xstartup if the desktop comes up blank."
+        ];
+      }
+    };
+    linuxDesktopPlatform = new LinuxDesktopPlatform();
+  }
+});
+
+// ../core/dist/desktop/platforms/windows.js
+async function ensureBeeoHome3() {
+  const p = getPlatformAdapter();
+  const home = beeoHome();
+  if (!await p.exists(home)) {
+    await p.mkdir(home);
+  }
+}
+async function detectWindowsColdStartState() {
+  const p = getPlatformAdapter();
+  const port5900Listening = await p.tcpProbe("127.0.0.1", WIN_VNC_PORT, PORT_PROBE_TIMEOUT_MS2).catch(() => false);
+  const beeoFile = p.joinPath(beeoHome(), "vnc.password");
+  let beeoPasswordFileExists = false;
+  try {
+    const raw = await p.readFile(beeoFile);
+    beeoPasswordFileExists = raw.trim().length > 0;
+  } catch {
+    beeoPasswordFileExists = false;
+  }
+  const [tvnserverServiceExists, tvnserverRegistryExists] = await Promise.all([
+    detectViaPowerShell("(Get-Service tvnserver -ErrorAction SilentlyContinue) -ne $null"),
+    detectViaPowerShell(`Test-Path "${TVNSERVER_REG_PATH}"`)
+  ]);
+  return {
+    port5900Listening,
+    beeoPasswordFileExists,
+    tvnserverServiceExists,
+    tvnserverRegistryExists
+  };
+}
+async function detectViaPowerShell(expression) {
+  const p = getPlatformAdapter();
+  try {
+    const result = await p.exec("powershell", ["-NoProfile", "-Command", expression], { timeout: 5e3 });
+    if (result.code !== 0)
+      return false;
+    return result.stdout.trim().toLowerCase() === "true";
+  } catch {
+    return false;
+  }
+}
+async function runElevatedTvnserverConfig(password) {
+  if (!isShellSafeVncPassword(password)) {
+    return { ok: false, detail: "internal: refusing to embed shell-unsafe password" };
+  }
+  const p = getPlatformAdapter();
+  const encoded = encodeVncPasswordBytes(password);
+  const byteLiteral = Array.from(encoded).map((b) => `0x${b.toString(16).padStart(2, "0")}`).join(",");
+  const innerScript = [
+    `$bytes = [byte[]](${byteLiteral})`,
+    `Set-ItemProperty -Path '${TVNSERVER_REG_PATH}' -Name 'Password' -Value $bytes -Type Binary`,
+    `Set-ItemProperty -Path '${TVNSERVER_REG_PATH}' -Name 'AllowLoopback' -Value 1 -Type DWord`,
+    `Set-ItemProperty -Path '${TVNSERVER_REG_PATH}' -Name 'LoopbackOnly' -Value 1 -Type DWord`,
+    `Set-ItemProperty -Path '${TVNSERVER_REG_PATH}' -Name 'LocalInputPriority' -Value 1 -Type DWord`,
+    `Restart-Service -Name 'tvnserver' -Force`,
+    `exit 0`
+  ].join("; ");
+  const outerScript = `try {  $p = Start-Process powershell -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-Command',"${innerScript.replace(/"/g, '`"')}" -Verb RunAs -Wait -PassThru -ErrorAction Stop;  exit $p.ExitCode} catch {  if ($_.Exception.Message -match 'cancel|cancelled') { exit 1223 } else { Write-Error $_; exit 1 }}`;
+  try {
+    const result = await p.exec("powershell", ["-NoProfile", "-Command", outerScript], { timeout: POWERSHELL_TIMEOUT_MS });
+    if (result.code === 0)
+      return { ok: true };
+    if (result.code === 1223) {
+      return { ok: false, canceled: true, detail: "UAC denied" };
+    }
+    return {
+      ok: false,
+      detail: result.stderr.trim() || `exit ${result.code}`
+    };
+  } catch (e) {
+    return { ok: false, detail: describeError4(e) };
+  }
+}
+async function waitForPort2(port, timeoutMs) {
+  const p = getPlatformAdapter();
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await p.tcpProbe("127.0.0.1", port, PORT_PROBE_TIMEOUT_MS2).catch(() => false)) {
+      return true;
+    }
+    await sleep5(VERIFY_POLL_INTERVAL_MS2);
+  }
+  return false;
+}
+function sleep5(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function describeError4(e) {
+  if (e instanceof Error) {
+    const msg = e.message.split(/\r?\n/, 1)[0]?.trim();
+    return msg && msg.length > 0 ? msg : e.name;
+  }
+  return String(e);
+}
+var WIN_VNC_PORT, PORT_PROBE_TIMEOUT_MS2, VERIFY_TIMEOUT_MS2, VERIFY_POLL_INTERVAL_MS2, POWERSHELL_TIMEOUT_MS, TVNSERVER_REG_PATH, WINGET_PACKAGE_HINT, WINDOWS_VNC_INSTALL_HINT_LINES, WindowsDesktopPlatform, windowsDesktopPlatform;
+var init_windows = __esm({
+  "../core/dist/desktop/platforms/windows.js"() {
+    "use strict";
+    init_platform_adapter();
+    init_paths();
+    init_common();
+    WIN_VNC_PORT = 5900;
+    PORT_PROBE_TIMEOUT_MS2 = 200;
+    VERIFY_TIMEOUT_MS2 = 8e3;
+    VERIFY_POLL_INTERVAL_MS2 = 250;
+    POWERSHELL_TIMEOUT_MS = 6e4;
+    TVNSERVER_REG_PATH = "HKLM:\\SOFTWARE\\TightVNC\\Server";
+    WINGET_PACKAGE_HINT = "winget install GlavSoft.TightVNC --accept-package-agreements --accept-source-agreements --silent";
+    WINDOWS_VNC_INSTALL_HINT_LINES = [
+      "Tip: BeeOS desktop streaming on Windows uses TightVNC. To install:",
+      `  ${WINGET_PACKAGE_HINT}`,
+      "Then re-run `beeos init`. Set BEEOS_NO_DESKTOP=1 to suppress this hint."
+    ];
+    WindowsDesktopPlatform = class {
+      id = "windows";
+      async coldStart(opts) {
+        if (opts.noDesktop)
+          return { status: "skipped_opt_out" };
+        const log = opts.log ?? ((m) => console.log(m));
+        const p = getPlatformAdapter();
+        const state = await detectWindowsColdStartState();
+        if (!state.tvnserverServiceExists && !state.tvnserverRegistryExists) {
+          return {
+            status: "skipped_no_vnc_server",
+            warnings: [...WINDOWS_VNC_INSTALL_HINT_LINES]
+          };
+        }
+        const beeoPasswordFile = p.joinPath(beeoHome(), "vnc.password");
+        if (state.port5900Listening && state.beeoPasswordFileExists) {
+          let existing;
+          try {
+            existing = (await p.readFile(beeoPasswordFile)).trim() || void 0;
+          } catch {
+            existing = void 0;
+          }
+          return { status: "already_configured", vncPassword: existing };
+        }
+        if (!opts.prompt && !opts.yes) {
+          return { status: "skipped_no_tty" };
+        }
+        if (!opts.yes) {
+          log("");
+          log("BeeOS desktop streaming needs TightVNC configured for loopback access.");
+          log("This will:");
+          log("  - Generate an 8-char VNC viewer password");
+          log("  - Write it to HKLM\\SOFTWARE\\TightVNC\\Server (requires UAC)");
+          log("  - Restrict TightVNC to 127.0.0.1:5900 (loopback only)");
+          log("  - Restart the tvnserver service");
+          log("Windows will pop ONE UAC dialog. The CLI never sees your password \u2014");
+          log("only the elevated PowerShell child does, and only inside its own process.");
+          log("");
+          const answer = (await opts.prompt("Configure TightVNC for desktop streaming? [Y/n]: ")).trim();
+          if (answer !== "" && !/^y(es)?$/i.test(answer)) {
+            return { status: "user_declined" };
+          }
+        }
+        const newPassword = generateLegacyVncPassword();
+        if (!isShellSafeVncPassword(newPassword)) {
+          return {
+            status: "script_failed",
+            warnings: [
+              "windows cold-start: generated VNC password contained shell-unsafe characters; refusing to embed in PowerShell payload. Re-run `beeos init`."
+            ]
+          };
+        }
+        try {
+          await ensureBeeoHome3();
+          await p.writeFile(beeoPasswordFile, newPassword);
+          await p.chmod(beeoPasswordFile, 384).catch(() => void 0);
+        } catch (e) {
+          return {
+            status: "script_failed",
+            warnings: [
+              `windows cold-start: failed to write ${beeoPasswordFile}: ${describeError4(e)}. Desktop streaming will not work this run.`
+            ]
+          };
+        }
+        log("Requesting Windows administrator privileges (UAC dialog) ...");
+        const elevated = await runElevatedTvnserverConfig(newPassword);
+        if (!elevated.ok) {
+          await p.rm(beeoPasswordFile).catch(() => void 0);
+          const canceled = elevated.canceled === true;
+          return {
+            status: canceled ? "user_canceled_dialog" : "script_failed",
+            warnings: [
+              canceled ? "windows cold-start: UAC dialog was canceled \u2014 desktop streaming not enabled." : `windows cold-start: tvnserver registry write failed: ${elevated.detail}. Desktop streaming will not work this run.`
+            ]
+          };
+        }
+        const up = await waitForPort2(WIN_VNC_PORT, VERIFY_TIMEOUT_MS2);
+        if (!up) {
+          return {
+            status: "verify_timeout",
+            warnings: [
+              `windows cold-start ran but :${WIN_VNC_PORT} never came up within 8s. Open Services.msc and check \`tvnserver\`, or run \`beeos doctor\`.`
+            ]
+          };
+        }
+        log(`tvnserver is listening on 127.0.0.1:${WIN_VNC_PORT}.`);
+        return { status: "enabled_now", vncPassword: newPassword };
+      }
+      async probe(opts) {
+        if (process.env.BEEOS_NO_DESKTOP === "1")
+          return null;
+        const p = getPlatformAdapter();
+        if (p.platform() !== "win32")
+          return null;
+        const ok = await p.tcpProbe("127.0.0.1", WIN_VNC_PORT, PORT_PROBE_TIMEOUT_MS2).catch(() => false);
+        if (!ok) {
+          if (opts?.ttyHints) {
+            for (const line of WINDOWS_VNC_INSTALL_HINT_LINES)
+              console.log(line);
+          }
+          return null;
+        }
+        return {
+          kind: "linux",
+          // VncEndpoint.kind is a coarse RFB-family tag; "linux"
+          // is fine because TightVNC speaks the same RFB scheme-2 surface
+          // as TigerVNC. We deliberately pin osType="windows-desktop" so
+          // the backend `isDesktopInstance` matcher sees the right host
+          // tag without having to extend the union.
+          host: "127.0.0.1",
+          port: WIN_VNC_PORT,
+          osType: "windows-desktop"
+        };
+      }
+      readPasswordOptional() {
+        return readVncPasswordFromBeeoHome();
+      }
+      postSetupHint(_endpoint) {
+        return [
+          "Windows desktop streaming notes:",
+          "  \u2022 TightVNC is configured to accept loopback connections only \u2014 exposing it externally",
+          "    requires extra Windows Firewall + auth rules outside BeeOS.",
+          "  \u2022 If the dashboard's desktop view stays blank, open Services.msc and verify",
+          "    that `tvnserver` is in the Running state."
+        ];
+      }
+    };
+    windowsDesktopPlatform = new WindowsDesktopPlatform();
+  }
+});
+
+// ../core/dist/desktop/hints.js
+var LINUX_DESKTOP_DOCTOR_HINT_LINES, WINDOWS_DESKTOP_DOCTOR_HINT_LINES;
+var init_hints = __esm({
+  "../core/dist/desktop/hints.js"() {
+    "use strict";
+    LINUX_DESKTOP_DOCTOR_HINT_LINES = [
+      "vnc-bridge-openclaw is failing on Linux. Likely causes:",
+      "  \u2022 `vncserver :1` is not running on 127.0.0.1:5901 \u2014 start it with",
+      "    `vncserver :1 -localhost yes -SecurityTypes VncAuth` and re-run",
+      "    `beeos doctor`.",
+      "  \u2022 ~/.vnc/passwd drifted out of sync with ~/.beeos/vnc.password \u2014",
+      "    re-run `beeos init` to regenerate both files in lockstep.",
+      "  \u2022 Headless box: ~/.vnc/xstartup boots into a black session \u2014 install",
+      "    a desktop environment (`xfce4`, `gnome-session`, \u2026) and add it to",
+      "    the xstartup line."
+    ];
+    WINDOWS_DESKTOP_DOCTOR_HINT_LINES = [
+      "vnc-bridge-openclaw is failing on Windows. Likely causes:",
+      "  \u2022 `tvnserver` service is stopped \u2014 open Services.msc, find",
+      "    `TightVNC Server`, click Start. Or re-run `beeos init` to",
+      "    re-apply the cold-start configuration.",
+      "  \u2022 Someone changed the TightVNC password outside BeeOS \u2014",
+      "    `HKLM\\SOFTWARE\\TightVNC\\Server\\Password` no longer matches",
+      "    %USERPROFILE%\\.beeos\\vnc.password. Re-run `beeos init` to",
+      "    regenerate both ends in one shot (UAC dialog will appear).",
+      "  \u2022 Windows Firewall is blocking the loopback bridge \u2014 TightVNC",
+      "    is configured for AllowLoopback=1 + LoopbackOnly=1, but a",
+      "    firewall rule that blocks 127.0.0.1:5900 will still break it."
+    ];
+  }
+});
+
+// ../core/dist/desktop/index.js
+function inferDesktopPlatformId(plat) {
+  switch (plat) {
+    case "darwin":
+      return "macos";
+    case "linux":
+      return "linux";
+    case "win32":
+      return "windows";
+    default:
+      return null;
+  }
+}
+function getDesktopPlatform() {
+  const plat = getPlatformAdapter().platform();
+  const id = inferDesktopPlatformId(plat);
+  switch (id) {
+    case "macos":
+      return macosDesktopPlatform;
+    case "linux":
+      return linuxDesktopPlatform;
+    case "windows":
+      return windowsDesktopPlatform;
+    default:
+      return linuxDesktopPlatform;
+  }
+}
+function getDesktopPipeline() {
+  if (process.env.BEEOS_NO_DESKTOP === "1")
+    return null;
+  return new DesktopPipeline(getDesktopPlatform());
+}
+var init_desktop = __esm({
+  "../core/dist/desktop/index.js"() {
+    "use strict";
+    init_platform_adapter();
+    init_pipeline();
+    init_macos();
+    init_linux();
+    init_windows();
+    init_pipeline();
+    init_common();
+    init_hints();
+  }
+});
+
 // ../core/dist/detect.js
 async function detectExistingInstall() {
   const p = getPlatformAdapter();
@@ -3788,35 +4590,6 @@ var init_registry = __esm({
   }
 });
 
-// ../core/dist/services/target-spec.js
-function buildVncBridgeTargetSpec(binary, opts) {
-  return {
-    id: `vnc-bridge-${opts.serial}`,
-    kind: "vnc-bridge",
-    command: binary,
-    args: [],
-    env: vncBridgeRuntime.buildEnv(opts),
-    restart: "on-failure",
-    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";
-  }
-});
-
 // ../core/dist/services/ids.js
 import path from "path";
 function safeId(id) {
@@ -5414,6 +6187,7 @@ var init_dist = __esm({
     init_agent_status();
     init_desktop_detect();
     init_macos_desktop_cold_start();
+    init_desktop();
     init_detect();
     init_registry();
     init_target_spec();
@@ -5936,6 +6710,20 @@ function resolvePerDeviceAgentGatewayUrl(cfg, override) {
   }
   return trimmed;
 }
+function resolveBackendForAttach(options, hostBackend) {
+  if (options.self === true) {
+    if (hostBackend === null || hostBackend === "self" || hostBackend === "adb") {
+      throw new BeeosError({
+        code: "self_attach_unsupported_os",
+        message: "`beeos device attach --self` is not supported on this host yet.",
+        hint: "Self-attach maps the host's native backend (macOS/Linux/Windows). Run on a supported OS, or attach an ADB device with `--serial` instead."
+      });
+    }
+    return hostBackend;
+  }
+  if (options.vncHost) return void 0;
+  return "adb";
+}
 async function pickAttachSerial() {
   const devices = await deviceRuntime.listAdbDevices();
   const ready = devices.filter((d) => d.status === "device");
@@ -6009,7 +6797,10 @@ async function attach(options) {
       });
       const fp = fingerprintFromB64(pubkeyB64);
       const boundAt = Math.floor(Date.now() / 1e3);
-      const backend = options.vncHost ? void 0 : "adb";
+      const backend = resolveBackendForAttach(
+        options,
+        inferHostBackend()
+      );
       state.devices.push({
         serial,
         name,
@@ -6017,12 +6808,6 @@ async function attach(options) {
         key_file: keyFile,
         http_port: httpPort,
         video_mode: bridgeInfo.mode,
-        // For now `beeos device attach` only binds ADB devices (the
-        // `--vnc-host` shape spawns a vnc-bridge but does NOT spawn a
-        // device-mcp-server, so `backend` only ever drives the ADB
-        // path through fleet → mcp). When self-attach for
-        // macOS/Linux/Windows lands, this field will be set
-        // accordingly (`macos`/`linux`/`windows`).
         backend,
         vnc_host: options.vncHost,
         vnc_port: options.vncPort,
@@ -6262,7 +7047,7 @@ async function runAttachStage2(params) {
       key_file: keyFile,
       http_port: httpPort,
       video_mode: bridgeInfo.mode,
-      backend: options.vncHost ? void 0 : "adb",
+      backend: resolveBackendForAttach(options, inferHostBackend()),
       vnc_host: options.vncHost,
       vnc_port: options.vncPort,
       // P0-D: see attach() above — every new entry self-pins to the
@@ -6371,7 +7156,7 @@ function shouldOfferFleetEnable(inputs = {
   stdoutIsTTY: process.stdout.isTTY,
   env: process.env
 }) {
-  if (inputs.platform !== "darwin") return false;
+  if (inputs.platform !== "darwin" && inputs.platform !== "linux") return false;
   if (inputs.env.BEEOS_NO_FLEET_AUTOSTART === "1") return false;
   if (!inputs.stdinIsTTY) return false;
   if (!inputs.stdoutIsTTY) return false;
@@ -7112,23 +7897,24 @@ async function run(agentFramework, options) {
   const launchWarnings = [...launchOutcome.warnings];
   reporter.stop();
   const ttyHints = !options.json && process.stdin.isTTY === true;
+  const desktopCapable = hasDesktopCapability(driver);
+  const desktopPipeline = desktopCapable ? getDesktopPipeline() : null;
   let coldStart = null;
-  if (agentFramework === OPENCLAW_ID) {
+  if (desktopPipeline) {
     const interactive = !options.json && process.stdin.isTTY === true && process.stdout.isTTY === true;
-    coldStart = await macosDesktopColdStart({
+    coldStart = await desktopPipeline.coldStart({
       prompt: interactive ? promptYesNo : void 0,
       log: options.json ? () => void 0 : (m) => console.log(m),
-      yes: options.force === true,
-      noDesktop: process.env.BEEOS_NO_DESKTOP === "1"
+      yes: options.force === true
     });
     if (coldStart.warnings && coldStart.warnings.length > 0) {
       launchWarnings.push(...coldStart.warnings);
     }
   }
-  const vncEndpoint = agentFramework === OPENCLAW_ID ? await probeLocalVnc({ ttyHints }) : null;
+  const vncEndpoint = desktopPipeline ? await desktopPipeline.probe({ ttyHints }) : null;
   const hostname = buildHostname();
   const cachedBinding = await loadBindingInfo();
-  const bindVncPassword = vncEndpoint ? await readVncPasswordOptional() : void 0;
+  const bindVncPassword = vncEndpoint && desktopPipeline ? await desktopPipeline.readPasswordOptional() : void 0;
   const outcome = await bindAgent({
     apiUrl: cfg.platform.api_url,
     dashboardBaseUrl: cfg.platform.dashboard_base_url,
@@ -7242,18 +8028,36 @@ async function run(agentFramework, options) {
       });
     }
   }
-  if (vncEndpoint && !isOffline) {
-    if (vncEndpoint.kind === "macos" && ttyHints) {
-      printMacosDesktopHint();
+  if (vncEndpoint && !isOffline && desktopPipeline && hasDesktopCapability(driver)) {
+    const platformHints = desktopPipeline.postSetupHint(vncEndpoint);
+    if (platformHints.length > 0 && ttyHints) {
+      for (const line of platformHints) console.log(line);
     }
-    const desktopWarning = await tryAttachOpenclawDesktopBridge({
+    const desktopReporter = new CliReporter();
+    const bridgeOutcome = await driver.desktopBridgeSpec(
       vncEndpoint,
-      instanceId: boundInstanceId,
-      keyFile,
-      agentGatewayUrl,
-      mgr
-    });
-    if (desktopWarning) launchWarnings.push(desktopWarning);
+      {
+        instanceId: boundInstanceId,
+        keyFile,
+        agentGatewayUrl,
+        ...bindVncPassword ? { vncPassword: bindVncPassword } : {}
+      },
+      desktopReporter
+    );
+    desktopReporter.stop();
+    if (bridgeOutcome.warnings.length > 0) {
+      launchWarnings.push(...bridgeOutcome.warnings);
+    }
+    if (bridgeOutcome.spec) {
+      try {
+        await mgr.install(bridgeOutcome.spec);
+      } catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        launchWarnings.push(
+          `vnc-bridge service install failed: ${reason}; ${driver.displayName} is bound but desktop streaming is unavailable. Re-run \`beeos start ${agentFramework} --force\` to retry.`
+        );
+      }
+    }
   }
   const gatewayPid = status2.pid ?? void 0;
   emit(options.json, {
@@ -7267,50 +8071,6 @@ 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 vncPassword = await readVncPasswordOptional();
-  const spec = buildOpenclawDesktopVncBridgeSpec(binary, {
-    deviceId: params.instanceId,
-    vncHost: params.vncEndpoint.host,
-    vncPort: params.vncEndpoint.port,
-    ...vncPassword ? { vncPassword } : {},
-    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;
-}
-async function readVncPasswordOptional() {
-  const env = process.env.BEEOS_VNC_PASSWORD?.trim();
-  if (env) return env;
-  const p = getPlatformAdapter();
-  const file = p.joinPath(beeoHome(), "vnc.password");
-  try {
-    const raw = (await p.readFile(file)).trim();
-    return raw || void 0;
-  } catch {
-    return void 0;
-  }
-}
 async function promptYesNo(question) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({
@@ -7794,6 +8554,9 @@ function printNextSteps() {
   console.log("Next steps:");
   console.log("  beeos status                  # show running agents");
   console.log("  beeos device attach           # bind a physical Android device");
+  if (inferDesktopPlatformId(process.platform) === "macos" || inferDesktopPlatformId(process.platform) === "linux") {
+    console.log("  beeos device attach --self    # (experimental) attach this Mac/Linux desktop directly");
+  }
   console.log("  beeos doctor                  # health check & diagnostics");
   console.log("");
 }
@@ -7952,10 +8715,10 @@ async function run8(options) {
         );
       }
       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);
-          }
+        const desktopId = inferDesktopPlatformId(process.platform);
+        const platformHints = desktopId === "macos" ? MACOS_DESKTOP_DOCTOR_HINT_LINES : desktopId === "linux" ? LINUX_DESKTOP_DOCTOR_HINT_LINES : desktopId === "windows" ? WINDOWS_DESKTOP_DOCTOR_HINT_LINES : null;
+        if (platformHints) {
+          for (const line of platformHints) 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.`
@@ -8443,6 +9206,9 @@ deviceCmd.command("attach").description("Attach an ADB-connected device as an AI
   "--vnc-host <host>",
   "Use vnc-bridge against a VNC server at this host (desktop/Linux/macOS). Implies video mode = vnc instead of scrcpy."
 ).option("--vnc-port <port>", "VNC TCP port (default 5900)", (v) => Number(v)).option("--vnc-password <password>", "VNC password (forwarded via env)").option(
+  "--self",
+  "(experimental) Tag the persisted DeviceEntry with the host's native backend (macOS/Linux/Windows) instead of `adb`. Forward-compatible with the upcoming self-attach lifecycle (Phase 4 of the multi-OS install-link refactor); today only the persisted backend tag changes."
+).option(
   "--agent-gateway-url <url>",
   "Override the Agent Gateway URL for THIS device only (advanced; multi-region staging). Persists to the device entry so the fleet supervisor reuses it on every restart. Falls back to the global config when omitted."
 ).action(attach);