From 4400ecd81c2f89068f5809073e74c7cce08693f6 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 16 Sep 2026 05:10:52 +0000
Subject: [PATCH] Fix Windows openXYOS extract and use a native folder picker
 for source download.

NSIS no longer calls PowerShell to unzip into Program Files (spaces broke
quoting and left $INSTDIR\openxyos as README-only). Setup now expands the
prebuilt zip with tar.exe into both openxyos and openxyos-runtime, and
aborts if node.exe or dist/index.html is missing. First launch copies the
complete tree, including the staged runtime, to LocalAppData.

Organization "download latest openXYOS source" opens the same Wails folder
picker as project workdirs instead of a typed path or window.prompt.

Co-authored-by: XYAI Labs <haoboy8@gmail.com>
---
 CHANGELOG.md                                  |   1 +
 dashboard/src/locales/en.json                 |   4 +-
 dashboard/src/locales/zh.json                 |   4 +-
 dashboard/src/pages/Organization/index.tsx    | 110 +++++++++++-------
 .../pages/Organization/pickSourceDest.test.ts |  35 ++++++
 .../src/pages/Organization/pickSourceDest.ts  |  16 +++
 desktop/README.md                             |  21 ++--
 desktop/src/build/stage_openxyos_runtime.py   |  24 ++++
 desktop/src/build/windows/nsis/project.nsi    |  12 +-
 .../src/build/windows/nsis/wails_tools.nsh    |  99 ++++++++++++----
 desktop/src/process_sidecar.go                |  30 ++++-
 desktop/src/process_sidecar_test.go           | 109 +++++++++++++++++
 src/octop/modules/org_os/sidecar_launch.py    |   6 +-
 tests/unit/desktop/test_nsis_uninstall.py     |  43 ++++++-
 .../desktop/test_stage_openxyos_runtime.py    |  18 +++
 tests/unit/test_sidecar_launch.py             |  13 +++
 16 files changed, 463 insertions(+), 82 deletions(-)
 create mode 100644 dashboard/src/pages/Organization/pickSourceDest.test.ts
 create mode 100644 dashboard/src/pages/Organization/pickSourceDest.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 54cd2301..94e858ac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,6 +33,7 @@
 
 ### 修复
 
+- Windows 安装把预构建 openXYOS 运行包用 `tar.exe` 解到 `$INSTDIR\openxyos` 与 `$INSTDIR\openxyos-runtime`（带空格的 `Program Files` 也能解全）。缺少 `node\node.exe` 或 `dist\index.html` 时安装失败，不再留下只有 README 的工作目录。首次启动会从完整树复制到 `%LOCALAPPDATA%\FreeOS\openxyos` 并自动拉起边车。组织页「下载最新 openXYOS 源码」走系统文件夹选择器（任意盘符），不再只用手输路径。
 - 桌面 / 本地会话不再被 `setup_required` 短路：`GET /setup/status` 之后仍可调用 `POST /auth/local-session`，不会误跳进服务端密码向导。
 - 组织页「启动边车」会拉起捆绑的 Node + openXYOS（Windows 用 `node.exe` / `cmd /c`，不再直接 Popen `.bat`），并在右侧预览区嵌入控制台（支持全屏）。openXYOS 在 FreeOS 桌面环境下关闭 `X-Frame-Options`，避免 iframe 空白。安装 / 桌面启动时宿主与 Wails 都会确保边车常开（需 `dist/index.html` 已打包）。
 - Windows 打开时不再因 WebView2 `Navigate`/`SetURL` 在 Chromium 未就绪时触发 Go panic。主窗口等 WebView 点火后再跳转；`SetURL` 失败会重试并显示 FreeOS 提示，而不是原始堆栈。设置窗口延后创建，避免两个 WebView2 同时初始化同一用户目录。用户数据目录必须可写，并设置 `WEBVIEW2_USER_DATA_FOLDER`。
diff --git a/dashboard/src/locales/en.json b/dashboard/src/locales/en.json
index 7660e674..f99907f0 100644
--- a/dashboard/src/locales/en.json
+++ b/dashboard/src/locales/en.json
@@ -98,10 +98,12 @@
     "fullscreen": "Fullscreen",
     "exitFullscreen": "Exit fullscreen",
     "downloadSource": "Download latest openXYOS source",
-    "downloadSourceHint": "Download the latest openXYOS main-branch source zip from GitHub into a folder you choose, for other deployments.",
+    "downloadSourceHint": "Pick any folder on any drive with the system dialog. FreeOS then downloads the latest openXYOS main-branch source from GitHub.",
     "downloadSourceDest": "Save to folder",
     "downloadSourceDone": "Downloaded to {{path}}",
     "downloadSourceFailed": "Could not download the source",
+    "browseDest": "Browse…",
+    "pickFolderFailed": "Could not open the folder picker",
     "catalogEnabled": "Shown",
     "catalogDisabled": "Hidden",
     "catalogToggleHint": "When off, the module disappears from the openXYOS preview sidebar.",
diff --git a/dashboard/src/locales/zh.json b/dashboard/src/locales/zh.json
index 48a45841..b6487b3b 100644
--- a/dashboard/src/locales/zh.json
+++ b/dashboard/src/locales/zh.json
@@ -98,10 +98,12 @@
     "fullscreen": "全屏",
     "exitFullscreen": "退出全屏",
     "downloadSource": "下载最新 openXYOS 源码",
-    "downloadSourceHint": "从 GitHub 下载 openXYOS 主分支源码 zip，保存到你选择的文件夹，便于在其他环境部署。",
+    "downloadSourceHint": "用系统文件夹选择器任选盘符与目录，FreeOS 会从 GitHub 下载最新 openXYOS 主分支源码。",
     "downloadSourceDest": "保存到文件夹",
     "downloadSourceDone": "已下载到 {{path}}",
     "downloadSourceFailed": "下载源码失败",
+    "browseDest": "浏览…",
+    "pickFolderFailed": "无法打开文件夹选择器",
     "catalogEnabled": "已显示",
     "catalogDisabled": "已隐藏",
     "catalogToggleHint": "关闭后，该模块会从右侧 openXYOS 预览的侧栏消失。",
diff --git a/dashboard/src/pages/Organization/index.tsx b/dashboard/src/pages/Organization/index.tsx
index 1b6e33b4..bc85210f 100644
--- a/dashboard/src/pages/Organization/index.tsx
+++ b/dashboard/src/pages/Organization/index.tsx
@@ -25,7 +25,12 @@ import {
 } from "../../api/modules/orgModule";
 import { formatServerIsoDateTime } from "../../utils/formatMessageTime";
 import { useServerTimezone } from "../../hooks/useServerTimezone";
+import {
+  canPickDesktopFolder,
+  pickDesktopFolder,
+} from "../../utils/desktopFolder";
 import { message } from "../../utils/antdMessage";
+import { resolveOpenxyosSourceDest } from "./pickSourceDest";
 import styles from "./Organization.module.less";
 
 type ActionKey = "assemble" | "pack" | "loop" | "sidecar" | "produce" | null;
@@ -51,6 +56,7 @@ export default function OrganizationPage() {
   );
   const [sourceDest, setSourceDest] = useState("");
   const [downloading, setDownloading] = useState(false);
+  const [pickingFolder, setPickingFolder] = useState(false);
   const [produceName, setProduceName] = useState("");
   const [produceIma, setProduceIma] = useState("");
   const [landed, setLanded] = useState<Record<string, unknown> | null>(null);
@@ -203,12 +209,7 @@ export default function OrganizationPage() {
     }
   };
 
-  const downloadSource = async () => {
-    const dest = sourceDest.trim();
-    if (!dest) {
-      message.error(t("organization.downloadSourceDest"));
-      return;
-    }
+  const saveSourceTo = async (dest: string) => {
     setDownloading(true);
     try {
       const result = await orgModuleApi.downloadSource(dest);
@@ -226,6 +227,51 @@ export default function OrganizationPage() {
     }
   };
 
+  const browseSourceDest = async () => {
+    setPickingFolder(true);
+    try {
+      const path = await pickDesktopFolder();
+      if (path) {
+        setSourceDest(path);
+      } else if (!canPickDesktopFolder()) {
+        message.info(t("organization.pickFolderFailed"));
+      }
+    } catch (err) {
+      message.error(
+        err instanceof Error ? err.message : t("organization.pickFolderFailed"),
+      );
+    } finally {
+      setPickingFolder(false);
+    }
+  };
+
+  const downloadSource = async () => {
+    setPickingFolder(true);
+    let dest: string | null = null;
+    try {
+      dest = await resolveOpenxyosSourceDest({
+        canPickNative: canPickDesktopFolder(),
+        pickNative: pickDesktopFolder,
+        typedDest: sourceDest,
+      });
+    } catch (err) {
+      message.error(
+        err instanceof Error ? err.message : t("organization.pickFolderFailed"),
+      );
+      setPickingFolder(false);
+      return;
+    }
+    setPickingFolder(false);
+    if (!dest) {
+      if (!canPickDesktopFolder()) {
+        message.error(t("organization.downloadSourceDest"));
+      }
+      return;
+    }
+    setSourceDest(dest);
+    await saveSourceTo(dest);
+  };
+
   const assemble = () =>
     runAction("assemble", async () => {
       const result: OrgAssembleResult = await orgModuleApi.assemble();
@@ -331,34 +377,8 @@ export default function OrganizationPage() {
           {(sidecarUp || overview?.enabled) && (
             <Button
               icon={<Package size={14} />}
-              onClick={() => {
-                const dest = window.prompt(
-                  t("organization.downloadSourceDest"),
-                );
-                if (dest) {
-                  setSourceDest(dest);
-                  void (async () => {
-                    setDownloading(true);
-                    try {
-                      const result = await orgModuleApi.downloadSource(dest);
-                      message.success(
-                        t("organization.downloadSourceDone", {
-                          path: result.path,
-                        }),
-                      );
-                    } catch (err) {
-                      message.error(
-                        err instanceof Error
-                          ? err.message
-                          : t("organization.downloadSourceFailed"),
-                      );
-                    } finally {
-                      setDownloading(false);
-                    }
-                  })();
-                }
-              }}
-              loading={downloading}
+              onClick={() => void downloadSource()}
+              loading={downloading || pickingFolder}
             >
               {t("organization.downloadSource")}
             </Button>
@@ -741,15 +761,23 @@ export default function OrganizationPage() {
                   {t("organization.downloadSourceHint")}
                 </p>
                 <Space wrap style={{ marginTop: 12 }}>
-                  <Input
-                    value={sourceDest}
-                    onChange={(event) => setSourceDest(event.target.value)}
-                    placeholder={t("organization.downloadSourceDest")}
-                    style={{ minWidth: 260 }}
-                  />
+                  <Space.Compact style={{ minWidth: 320 }}>
+                    <Input
+                      value={sourceDest}
+                      onChange={(event) => setSourceDest(event.target.value)}
+                      placeholder={t("organization.downloadSourceDest")}
+                      readOnly={canPickDesktopFolder()}
+                    />
+                    <Button
+                      loading={pickingFolder}
+                      onClick={() => void browseSourceDest()}
+                    >
+                      {t("organization.browseDest")}
+                    </Button>
+                  </Space.Compact>
                   <Button
                     type="primary"
-                    loading={downloading}
+                    loading={downloading || pickingFolder}
                     onClick={() => void downloadSource()}
                   >
                     {t("organization.downloadSource")}
diff --git a/dashboard/src/pages/Organization/pickSourceDest.test.ts b/dashboard/src/pages/Organization/pickSourceDest.test.ts
new file mode 100644
index 00000000..f2dae0bd
--- /dev/null
+++ b/dashboard/src/pages/Organization/pickSourceDest.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveOpenxyosSourceDest } from "./pickSourceDest";
+
+describe("resolveOpenxyosSourceDest", () => {
+  it("uses the native folder picker on desktop and ignores the typed path", async () => {
+    const pickNative = vi.fn().mockResolvedValue("D:\\src\\openxyos");
+    const dest = await resolveOpenxyosSourceDest({
+      canPickNative: true,
+      pickNative,
+      typedDest: "C:\\typed-only",
+    });
+    expect(pickNative).toHaveBeenCalled();
+    expect(dest).toBe("D:\\src\\openxyos");
+  });
+
+  it("returns null when the native picker is cancelled", async () => {
+    const dest = await resolveOpenxyosSourceDest({
+      canPickNative: true,
+      pickNative: async () => null,
+      typedDest: "C:\\typed-only",
+    });
+    expect(dest).toBeNull();
+  });
+
+  it("falls back to a typed path only outside the desktop shell", async () => {
+    const pickNative = vi.fn();
+    const dest = await resolveOpenxyosSourceDest({
+      canPickNative: false,
+      pickNative,
+      typedDest: "  /home/me/src  ",
+    });
+    expect(pickNative).not.toHaveBeenCalled();
+    expect(dest).toBe("/home/me/src");
+  });
+});
diff --git a/dashboard/src/pages/Organization/pickSourceDest.ts b/dashboard/src/pages/Organization/pickSourceDest.ts
new file mode 100644
index 00000000..fbe441b8
--- /dev/null
+++ b/dashboard/src/pages/Organization/pickSourceDest.ts
@@ -0,0 +1,16 @@
+/**
+ * Resolve where to save the latest openXYOS source zip.
+ * Desktop: native folder picker (any drive). Browser: typed path fallback.
+ */
+export async function resolveOpenxyosSourceDest(options: {
+  canPickNative: boolean;
+  pickNative: () => Promise<string | null>;
+  typedDest: string;
+}): Promise<string | null> {
+  if (options.canPickNative) {
+    const picked = await options.pickNative();
+    return picked && picked.trim() ? picked.trim() : null;
+  }
+  const typed = options.typedDest.trim();
+  return typed || null;
+}
diff --git a/desktop/README.md b/desktop/README.md
index 1ba38042..fd120a85 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -23,8 +23,9 @@ Same precedence as the FreeOS CLI/server:
 - Green runtime extract → `{home}/portable/`
 - Organization sidecar data → `{home}/org-os/`
 - Local openXYOS workdir (FE+BE) → `%LOCALAPPDATA%\FreeOS\openxyos` on Windows,
-  else `{home}/openxyos`. The NSIS installer also expands a prebuilt
-  `openxyos-runtime.zip` into `$INSTDIR\openxyos`. First unelevated start copies
+  else `{home}/openxyos`. The NSIS installer expands a prebuilt
+  `openxyos-runtime.zip` into `$INSTDIR\openxyos` and `$INSTDIR\openxyos-runtime`
+  (install fails if `node` or `dist` is missing). First unelevated start copies
   that tree into the workdir and starts `http://127.0.0.1:3780`.
 - Shell prefs → `{home}/desktop-settings.json`
 
@@ -39,11 +40,17 @@ with `makensis -INPUTCHARSET UTF8` from a UTF-8 BOM `project.nsi`.
 
 The install log is no longer only `FreeOS.exe` + shortcuts. A healthy package
 also copies `openxyos-runtime.zip` (prebuilt Node + openXYOS frontend/backend)
-and extracts it to `$INSTDIR\openxyos`. The durable workdir is
-`%LOCALAPPDATA%\FreeOS\openxyos` (and `{home}/openxyos`). Program Files is
-read-only, so first start — not the elevated installer — writes the user
-workdir. Organization then embeds `http://127.0.0.1:3780` without a manual
-「启动边车」 click.
+and extracts it with Windows `tar.exe` (quoted paths, so `Program Files`
+works) into **both** `$INSTDIR\openxyos` and `$INSTDIR\openxyos-runtime`.
+Setup **aborts** if `node\node.exe` or `dist\index.html` is missing after
+extract — a README-only `$INSTDIR\openxyos` is not a successful install.
+The durable workdir is `%LOCALAPPDATA%\FreeOS\openxyos` (and `{home}/openxyos`).
+Program Files is read-only, so first start — not the elevated installer —
+copies the complete tree into the user workdir (and will heal from
+`openxyos-runtime` if `openxyos` was left as a stub). Organization then
+embeds `http://127.0.0.1:3780` without a manual 「启动边车」 click.
+Downloading the latest openXYOS source uses the same native folder picker
+as the project workdir (any drive), not a typed path only.
 
 Override the workdir with `FREEOS_OPENXYOS_HOME`.
 
diff --git a/desktop/src/build/stage_openxyos_runtime.py b/desktop/src/build/stage_openxyos_runtime.py
index d3d563ab..50704264 100644
--- a/desktop/src/build/stage_openxyos_runtime.py
+++ b/desktop/src/build/stage_openxyos_runtime.py
@@ -20,6 +20,29 @@
 )
 
 
+def layout_ready(root: Path) -> bool:
+    """True when *root* is a complete sidecar tree, not README-only."""
+    node_ok = (root / "node" / "node.exe").is_file() or (root / "node" / "bin" / "node").is_file()
+    fe_ok = (root / "openxyos" / "dist" / "index.html").is_file() or (
+        root / "dist" / "index.html"
+    ).is_file()
+    be_ok = (root / "openxyos" / "backend" / "server.ts").is_file() or (
+        root / "backend" / "server.ts"
+    ).is_file()
+    return node_ok and fe_ok and be_ok
+
+
+def verify_runtime_zip(path: Path) -> None:
+    """Fail if the zip would install as README-only (missing node or dist)."""
+    with zipfile.ZipFile(path) as zf:
+        names = {name.replace("\\", "/").lstrip("./") for name in zf.namelist()}
+    node_ok = "node/node.exe" in names or "node/bin/node" in names
+    fe_ok = "openxyos/dist/index.html" in names or "dist/index.html" in names
+    be_ok = "openxyos/backend/server.ts" in names or "backend/server.ts" in names
+    if not (node_ok and fe_ok and be_ok):
+        raise SystemExit(f"incomplete openxyos-runtime.zip (need node + dist/index.html): {path}")
+
+
 def _bundle_root(extracted: Path) -> Path | None:
     direct = extracted
     if _ready(direct):
@@ -70,6 +93,7 @@ def stage(source: Path, dest_zip: Path) -> Path:
                 continue
             rel = path.relative_to(root).as_posix()
             zf.write(path, rel)
+    verify_runtime_zip(dest_zip)
     readme = dest_zip.with_name("openxyos-README.txt")
     readme.write_text(
         "FreeOS openXYOS runtime\n"
diff --git a/desktop/src/build/windows/nsis/project.nsi b/desktop/src/build/windows/nsis/project.nsi
index 2d863783..bdfec31e 100644
--- a/desktop/src/build/windows/nsis/project.nsi
+++ b/desktop/src/build/windows/nsis/project.nsi
@@ -60,14 +60,14 @@ LangString OPENXYOS_EXTRACT ${LANG_SIMPCHINESE} "解压 openXYOS 前端与后端
 LangString OPENXYOS_EXTRACT ${LANG_ENGLISH} "Extract openXYOS frontend and backend into the install dir\\openxyos"
 LangString OPENXYOS_FE_OK ${LANG_SIMPCHINESE} "已就绪：openxyos\\dist\\index.html"
 LangString OPENXYOS_FE_OK ${LANG_ENGLISH} "Ready: openxyos\\dist\\index.html"
-LangString OPENXYOS_FE_MISSING ${LANG_SIMPCHINESE} "警告：未找到 openXYOS 前端构建，首次启动将再试"
-LangString OPENXYOS_FE_MISSING ${LANG_ENGLISH} "Warning: openXYOS frontend build missing; first launch will retry"
 LangString OPENXYOS_NODE_OK ${LANG_SIMPCHINESE} "已就绪：bundled Node（node.exe）"
 LangString OPENXYOS_NODE_OK ${LANG_ENGLISH} "Ready: bundled Node (node.exe)"
-LangString OPENXYOS_NODE_MISSING ${LANG_SIMPCHINESE} "警告：未找到 bundled Node，首次启动将再试"
-LangString OPENXYOS_NODE_MISSING ${LANG_ENGLISH} "Warning: bundled Node missing; first launch will retry"
-LangString OPENXYOS_ZIP_MISSING ${LANG_SIMPCHINESE} "安装包未含独立 openXYOS zip；首次启动会从内置 portable 解压"
-LangString OPENXYOS_ZIP_MISSING ${LANG_ENGLISH} "Installer has no separate openXYOS zip; first launch unpacks the bundled portable"
+LangString OPENXYOS_STAGED_OK ${LANG_SIMPCHINESE} "已从 openxyos-runtime 展开完整运行树"
+LangString OPENXYOS_STAGED_OK ${LANG_ENGLISH} "Expanded the full runtime from openxyos-runtime"
+LangString OPENXYOS_EXTRACT_CODE ${LANG_SIMPCHINESE} "解压结束，退出码 "
+LangString OPENXYOS_EXTRACT_CODE ${LANG_ENGLISH} "Extract finished, exit code "
+LangString OPENXYOS_EXTRACT_FAIL ${LANG_SIMPCHINESE} "安装失败：未能解压完整的 openXYOS 运行环境（需要 node\\node.exe 与 dist\\index.html）。请重新下载安装包。"
+LangString OPENXYOS_EXTRACT_FAIL ${LANG_ENGLISH} "Setup failed: openXYOS runtime is incomplete (need node\\node.exe and dist\\index.html). Download the installer again."
 LangString UN_FREEOS_RUNNING ${LANG_SIMPCHINESE} "检测到 FreeOS 仍在运行（主程序、主机或组织侧车）。$\r$\n$\r$\n继续将结束这些进程，并删除安装目录中的程序文件。$\r$\n用户数据（%USERPROFILE%\.freeos）会保留。$\r$\n$\r$\n要继续卸载吗？"
 LangString UN_FREEOS_RUNNING ${LANG_ENGLISH} "FreeOS is still running (shell, host, or organization sidecar).$\r$\n$\r$\nContinuing will stop those processes and remove program files from the install folder.$\r$\nUser data (%USERPROFILE%\.freeos) is kept.$\r$\n$\r$\nContinue uninstall?"
 
diff --git a/desktop/src/build/windows/nsis/wails_tools.nsh b/desktop/src/build/windows/nsis/wails_tools.nsh
index 3916fb2b..bfb73e0b 100644
--- a/desktop/src/build/windows/nsis/wails_tools.nsh
+++ b/desktop/src/build/windows/nsis/wails_tools.nsh
@@ -34,6 +34,17 @@
     !define WAILS_INSTALL_SCOPE "machine"
 !endif
 
+# Prebuilt FE+BE zip must exist when makensis runs (CI: stage:openxyos-runtime).
+# A README-only $INSTDIR\openxyos is not a shippable installer.
+!ifndef OPENXYOS_RUNTIME_ZIP
+    !define OPENXYOS_RUNTIME_ZIP "..\openxyos-runtime.zip"
+!endif
+!if /FileExists "${OPENXYOS_RUNTIME_ZIP}"
+    !define OPENXYOS_RUNTIME_ZIP_PRESENT
+!else
+    !error "openxyos-runtime.zip missing at desktop/src/build/windows/openxyos-runtime.zip; run stage:openxyos-runtime before makensis"
+!endif
+
 !ifndef REQUEST_EXECUTION_LEVEL
     !if "${WAILS_INSTALL_SCOPE}" == "user"
         !define REQUEST_EXECUTION_LEVEL "user"
@@ -126,43 +137,87 @@ RequestExecutionLevel "${REQUEST_EXECUTION_LEVEL}"
 # Ship the prebuilt openXYOS FE+BE next to FreeOS.exe and expand it so the
 # finish log is not just FreeOS.exe + shortcuts. First unelevated start also
 # copies this tree into %LOCALAPPDATA%\FreeOS\openxyos (Program Files is read-only).
+#
+# Do NOT call PowerShell to unzip with NSIS ''$INSTDIR'' quoting: "Program
+# Files" splits the command, extract silently fails, and $INSTDIR\openxyos is
+# left README-only. Write a .cmd (paths expanded at install time) and use
+# Windows 10+ tar.exe, which accepts quoted paths with spaces.
 !macro wails.provisionOpenXYOS
     SetDetailsPrint both
     DetailPrint "$(OPENXYOS_WORKDIR)"
     CreateDirectory "$INSTDIR\openxyos"
+    CreateDirectory "$INSTDIR\openxyos-runtime"
     CreateDirectory "$LOCALAPPDATA\FreeOS\openxyos"
+    DetailPrint "$(OPENXYOS_COPY_ZIP)"
+    File "/oname=openxyos-runtime.zip" "${OPENXYOS_RUNTIME_ZIP}"
+    DetailPrint "$(OPENXYOS_EXTRACT)"
+    InitPluginsDir
+    FileOpen $0 "$PLUGINSDIR\extract-openxyos.cmd" w
+    FileWrite $0 `@echo off$\r$\n`
+    FileWrite $0 `set "TAR=$SYSDIR\tar.exe"$\r$\n`
+    FileWrite $0 `if not exist "$INSTDIR\openxyos-runtime.zip" exit /b 2$\r$\n`
+    FileWrite $0 `if not exist "%TAR%" exit /b 5$\r$\n`
+    FileWrite $0 `if not exist "$INSTDIR\openxyos-runtime" mkdir "$INSTDIR\openxyos-runtime"$\r$\n`
+    FileWrite $0 `if not exist "$INSTDIR\openxyos" mkdir "$INSTDIR\openxyos"$\r$\n`
+    FileWrite $0 `"%TAR%" -xf "$INSTDIR\openxyos-runtime.zip" -C "$INSTDIR\openxyos-runtime"$\r$\n`
+    FileWrite $0 `if errorlevel 1 exit /b 3$\r$\n`
+    FileWrite $0 `"%TAR%" -xf "$INSTDIR\openxyos-runtime.zip" -C "$INSTDIR\openxyos"$\r$\n`
+    FileWrite $0 `if errorlevel 1 exit /b 4$\r$\n`
+    FileClose $0
+    nsExec::ExecToLog '"$PLUGINSDIR\extract-openxyos.cmd"'
+    Pop $0
+    DetailPrint "$(OPENXYOS_EXTRACT_CODE)$0"
+    !insertmacro wails.requireOpenXYOSLayout
     FileOpen $0 "$INSTDIR\openxyos\README.txt" w
     FileWrite $0 "FreeOS local openXYOS environment$\r$\n"
     FileWrite $0 "Install tree: $INSTDIR\openxyos$\r$\n"
+    FileWrite $0 "Staged tree: $INSTDIR\openxyos-runtime$\r$\n"
     FileWrite $0 "Work dir: $LOCALAPPDATA\FreeOS\openxyos$\r$\n"
     FileWrite $0 "Also: %USERPROFILE%\.freeos\openxyos$\r$\n"
     FileWrite $0 "URL: http://127.0.0.1:3780$\r$\n"
     FileClose $0
-    !if /FileExists "..\openxyos-runtime.zip"
-        DetailPrint "$(OPENXYOS_COPY_ZIP)"
-        File "/oname=openxyos-runtime.zip" "..\openxyos-runtime.zip"
-        DetailPrint "$(OPENXYOS_EXTRACT)"
-        nsExec::ExecToLog 'powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "Expand-Archive -LiteralPath ''$INSTDIR\openxyos-runtime.zip'' -DestinationPath ''$INSTDIR\openxyos'' -Force"'
-        IfFileExists "$INSTDIR\openxyos\openxyos\dist\index.html" openxyosFeOk openxyosFeMissing
-        openxyosFeOk:
-            DetailPrint "$(OPENXYOS_FE_OK)"
-            Goto openxyosFeDone
-        openxyosFeMissing:
-            DetailPrint "$(OPENXYOS_FE_MISSING)"
-        openxyosFeDone:
-        IfFileExists "$INSTDIR\openxyos\node\node.exe" openxyosNodeOk openxyosNodeMissing
-        openxyosNodeOk:
-            DetailPrint "$(OPENXYOS_NODE_OK)"
-            Goto openxyosNodeDone
-        openxyosNodeMissing:
-            DetailPrint "$(OPENXYOS_NODE_MISSING)"
-        openxyosNodeDone:
-    !else
-        DetailPrint "$(OPENXYOS_ZIP_MISSING)"
-    !endif
     SetDetailsPrint listonly
 !macroend
 
+# Live workdir is $INSTDIR\openxyos (node + openxyos\dist, or flattened dist).
+# openxyos-runtime is the fully expanded zip (heals first-run if live is stub).
+# Missing node.exe or dist\index.html aborts setup — never ship README-only.
+!macro wails.requireOpenXYOSLayout
+    IfFileExists "$INSTDIR\openxyos\node\node.exe" 0 openxyosTryStaged
+    IfFileExists "$INSTDIR\openxyos\openxyos\dist\index.html" openxyosLiveOk openxyosTryFlat
+    openxyosTryFlat:
+    IfFileExists "$INSTDIR\openxyos\dist\index.html" openxyosLiveOk openxyosTryStaged
+    openxyosLiveOk:
+        DetailPrint "$(OPENXYOS_FE_OK)"
+        DetailPrint "$(OPENXYOS_NODE_OK)"
+        Goto openxyosLayoutDone
+    openxyosTryStaged:
+    IfFileExists "$INSTDIR\openxyos-runtime\node\node.exe" 0 openxyosLayoutFail
+    IfFileExists "$INSTDIR\openxyos-runtime\openxyos\dist\index.html" 0 openxyosTryStagedFlat
+        Goto openxyosCopyStaged
+    openxyosTryStagedFlat:
+    IfFileExists "$INSTDIR\openxyos-runtime\dist\index.html" 0 openxyosLayoutFail
+    openxyosCopyStaged:
+        DetailPrint "$(OPENXYOS_STAGED_OK)"
+        nsExec::ExecToLog '"$SYSDIR\cmd.exe" /C xcopy /E /I /Y "$INSTDIR\openxyos-runtime\*" "$INSTDIR\openxyos\"'
+        Pop $0
+        IfFileExists "$INSTDIR\openxyos\node\node.exe" 0 openxyosLayoutFail
+        IfFileExists "$INSTDIR\openxyos\openxyos\dist\index.html" openxyosLiveOk openxyosTryFlatAfterCopy
+        openxyosTryFlatAfterCopy:
+        IfFileExists "$INSTDIR\openxyos\dist\index.html" openxyosLiveOk openxyosLayoutFail
+    openxyosLayoutFail:
+        DetailPrint "$(OPENXYOS_EXTRACT_FAIL)"
+        IfSilent openxyosSilentFail openxyosLoudFail
+        openxyosSilentFail:
+            SetErrorLevel 67
+            Abort
+        openxyosLoudFail:
+            MessageBox MB_OK|MB_ICONSTOP "$(OPENXYOS_EXTRACT_FAIL)"
+            SetErrorLevel 67
+            Abort
+    openxyosLayoutDone:
+!macroend
+
 !macro wails.writeUninstaller
     WriteUninstaller "$INSTDIR\uninstall.exe"
 
diff --git a/desktop/src/process_sidecar.go b/desktop/src/process_sidecar.go
index 3ced86ae..4fcdd6f8 100644
--- a/desktop/src/process_sidecar.go
+++ b/desktop/src/process_sidecar.go
@@ -83,7 +83,13 @@ func openxyosUserWorkDir() string {
 	return filepath.Join(productHome(), "openxyos")
 }
 
-func openxyosInstallDir() string {
+// installerRootOverride is a test seam for a fake $INSTDIR (Program Files).
+var installerRootOverride string
+
+func installerRoot() string {
+	if installerRootOverride != "" {
+		return installerRootOverride
+	}
 	exe, err := os.Executable()
 	if err != nil {
 		return ""
@@ -92,7 +98,23 @@ func openxyosInstallDir() string {
 	if resolved, err := filepath.EvalSymlinks(dir); err == nil {
 		dir = resolved
 	}
-	return filepath.Join(dir, "openxyos")
+	return dir
+}
+
+func openxyosInstallDir() string {
+	root := installerRoot()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "openxyos")
+}
+
+func openxyosStagedRuntimeDir() string {
+	root := installerRoot()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "openxyos-runtime")
 }
 
 func sidecarSearchDirs(portableRoot string) []string {
@@ -114,6 +136,7 @@ func sidecarSearchDirs(portableRoot string) []string {
 	add(openxyosUserWorkDir())
 	add(filepath.Join(productHome(), "openxyos"))
 	add(openxyosInstallDir())
+	add(openxyosStagedRuntimeDir())
 	if portableRoot != "" {
 		add(orgSidecarDir(portableRoot))
 	}
@@ -323,6 +346,9 @@ func openxyosSourceDirs(portableRoot string) []string {
 	if install := openxyosInstallDir(); install != "" {
 		out = append(out, install)
 	}
+	if staged := openxyosStagedRuntimeDir(); staged != "" {
+		out = append(out, staged)
+	}
 	if portableRoot != "" {
 		out = append(out, orgSidecarDir(portableRoot))
 	}
diff --git a/desktop/src/process_sidecar_test.go b/desktop/src/process_sidecar_test.go
index fb5e4354..560c978a 100644
--- a/desktop/src/process_sidecar_test.go
+++ b/desktop/src/process_sidecar_test.go
@@ -1,6 +1,8 @@
 package main
 
 import (
+	"archive/zip"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
@@ -142,6 +144,113 @@ func writeSidecarBundle(t *testing.T, bundle string) {
 	}
 }
 
+func TestSidecarBundleReadyRejectsReadmeOnly(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "README.txt"), []byte("stub"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if sidecarBundleReady(dir) {
+		t.Fatal("README-only tree must not be treated as a runtime")
+	}
+}
+
+func TestProvisionOpenXYOSHealsFromStagedRuntime(t *testing.T) {
+	root := t.TempDir()
+	t.Setenv("FREEOS_HOME", root)
+	work := filepath.Join(root, "workdir")
+	t.Setenv("FREEOS_OPENXYOS_HOME", work)
+	t.Setenv("LOCALAPPDATA", filepath.Join(root, "local"))
+	inst := filepath.Join(root, "Program Files", "FreeOS")
+	installerRootOverride = inst
+	t.Cleanup(func() { installerRootOverride = "" })
+	live := filepath.Join(inst, "openxyos")
+	if err := os.MkdirAll(live, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(live, "README.txt"), []byte("stub"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	writeSidecarBundle(t, filepath.Join(inst, "openxyos-runtime"))
+	got, err := provisionOpenXYOS(filepath.Join(root, "portable"), LocaleEN, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != work {
+		t.Fatalf("provision dest=%q want %q", got, work)
+	}
+	if !sidecarBundleReady(work) {
+		t.Fatal("workdir should be copied from openxyos-runtime, not README-only openxyos")
+	}
+	if _, err := os.Stat(filepath.Join(work, "openxyos", "dist", "index.html")); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestUnzipSidecarZipLaysOutBundle(t *testing.T) {
+	root := t.TempDir()
+	bundle := filepath.Join(root, "bundle")
+	writeSidecarBundle(t, bundle)
+	zipPath := filepath.Join(root, "openxyos-runtime.zip")
+	if err := zipDir(bundle, zipPath); err != nil {
+		t.Fatal(err)
+	}
+	dest := filepath.Join(root, "Program Files", "FreeOS", "openxyos")
+	if err := unzipSidecarZip(zipPath, dest); err != nil {
+		t.Fatal(err)
+	}
+	if !sidecarBundleReady(dest) {
+		t.Fatal("extracted zip should be a complete sidecar")
+	}
+}
+
+func zipDir(src, dest string) error {
+	f, err := os.Create(dest)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	w := zip.NewWriter(f)
+	err = filepath.Walk(src, func(path string, info os.FileInfo, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+		rel, err := filepath.Rel(src, path)
+		if err != nil {
+			return err
+		}
+		if rel == "." {
+			return nil
+		}
+		name := filepath.ToSlash(rel)
+		if info.IsDir() {
+			_, err := w.Create(name + "/")
+			return err
+		}
+		hdr, err := zip.FileInfoHeader(info)
+		if err != nil {
+			return err
+		}
+		hdr.Name = name
+		hdr.Method = zip.Deflate
+		out, err := w.CreateHeader(hdr)
+		if err != nil {
+			return err
+		}
+		in, err := os.Open(path)
+		if err != nil {
+			return err
+		}
+		_, copyErr := io.Copy(out, in)
+		in.Close()
+		return copyErr
+	})
+	if err != nil {
+		w.Close()
+		return err
+	}
+	return w.Close()
+}
+
 func TestSidecarNodeArgsPrefersCompiledServer(t *testing.T) {
 	app := t.TempDir()
 	args := sidecarNodeArgs(app)
diff --git a/src/octop/modules/org_os/sidecar_launch.py b/src/octop/modules/org_os/sidecar_launch.py
index b0dbe864..59697fc1 100644
--- a/src/octop/modules/org_os/sidecar_launch.py
+++ b/src/octop/modules/org_os/sidecar_launch.py
@@ -148,7 +148,11 @@ def _bundle_looks_complete(path: Path) -> bool:
     node = path / "node" / "node.exe"
     posix = path / "node" / "bin" / "node"
     app = path / "openxyos"
-    return (node.is_file() or posix.is_file()) and (app / "backend" / "server.ts").is_file()
+    return (
+        (node.is_file() or posix.is_file())
+        and (app / "backend" / "server.ts").is_file()
+        and (app / "dist" / "index.html").is_file()
+    )
 
 
 def find_sidecar_runtime() -> SidecarRuntime | None:
diff --git a/tests/unit/desktop/test_nsis_uninstall.py b/tests/unit/desktop/test_nsis_uninstall.py
index d9e2f1e1..a60449e2 100644
--- a/tests/unit/desktop/test_nsis_uninstall.py
+++ b/tests/unit/desktop/test_nsis_uninstall.py
@@ -8,6 +8,7 @@
 NSI = REPO / "desktop" / "src" / "build" / "windows" / "nsis" / "project.nsi"
 NSH = REPO / "desktop" / "src" / "build" / "windows" / "nsis" / "wails_tools.nsh"
 DESKTOP_README = REPO / "desktop" / "README.md"
+ORG_PAGE = REPO / "dashboard" / "src" / "pages" / "Organization" / "index.tsx"
 
 
 def _uninstall_section(text: str) -> str:
@@ -141,8 +142,8 @@ def test_nsis_provisions_openxyos_runtime() -> None:
     assert "!insertmacro wails.provisionOpenXYOS" in nsh
     assert 'File "/oname=openxyos-runtime.zip"' in nsh
     assert r"$INSTDIR\openxyos" in nsh
+    assert r"$INSTDIR\openxyos-runtime" in nsh
     assert r"$LOCALAPPDATA\FreeOS\openxyos" in nsh
-    assert "Expand-Archive" in nsh
     assert "http://127.0.0.1:3780" in nsh
     assert "LangString OPENXYOS_WORKDIR ${LANG_SIMPCHINESE}" in nsi
     assert "创建 openXYOS 工作目录" in nsi
@@ -156,6 +157,34 @@ def test_nsis_provisions_openxyos_runtime() -> None:
     assert "openXYOS frontend missing" in package
 
 
+def test_nsis_extracts_runtime_with_quoted_paths_and_aborts_if_incomplete() -> None:
+    """Program Files spaces must not yield a README-only $INSTDIR\\openxyos."""
+    nsi = NSI.read_text(encoding="utf-8-sig")
+    nsh = NSH.read_text(encoding="utf-8")
+    provision = nsh[
+        nsh.index("!macro wails.provisionOpenXYOS") : nsh.index(
+            "!macro wails.requireOpenXYOSLayout"
+        )
+    ]
+    require = nsh[nsh.index("!macro wails.requireOpenXYOSLayout") :]
+    assert "Expand-Archive" not in nsh
+    assert "nsExec::ExecToLog" in provision and "tar.exe" in provision
+    assert "extract-openxyos.cmd" in provision
+    assert "tar.exe" in provision
+    assert r"$INSTDIR\openxyos-runtime.zip" in provision
+    assert "nsExec::ExecToLog" in provision
+    assert "Pop $0" in provision
+    assert r"$INSTDIR\openxyos\node\node.exe" in require
+    assert r"$INSTDIR\openxyos\openxyos\dist\index.html" in require
+    assert "Abort" in require
+    assert "SetErrorLevel 67" in require
+    assert "OPENXYOS_EXTRACT_FAIL" in require
+    assert "LangString OPENXYOS_EXTRACT_FAIL ${LANG_SIMPCHINESE}" in nsi
+    assert "未能解压完整的 openXYOS" in nsi
+    assert "openxyos-runtime.zip missing" in nsh
+    assert "!error" in nsh
+
+
 def test_desktop_readme_documents_uninstall_keep_vs_remove() -> None:
     text = DESKTOP_README.read_text(encoding="utf-8")
     assert "## Windows uninstall" in text
@@ -171,3 +200,15 @@ def test_desktop_readme_documents_uninstall_keep_vs_remove() -> None:
     assert "运行 FreeOS" in text
     assert "%LOCALAPPDATA%\\FreeOS\\openxyos" in text
     assert "127.0.0.1:3780" in text
+    assert "tar.exe" in text
+    assert "README-only" in text
+    assert "folder picker" in text
+
+
+def test_organization_source_download_uses_native_folder_picker() -> None:
+    page = ORG_PAGE.read_text(encoding="utf-8")
+    assert "window.prompt" not in page
+    assert "pickDesktopFolder" in page
+    assert "canPickDesktopFolder" in page
+    assert "resolveOpenxyosSourceDest" in page
+    assert "browseSourceDest" in page
diff --git a/tests/unit/desktop/test_stage_openxyos_runtime.py b/tests/unit/desktop/test_stage_openxyos_runtime.py
index 3bcf68c6..1b1cfd13 100644
--- a/tests/unit/desktop/test_stage_openxyos_runtime.py
+++ b/tests/unit/desktop/test_stage_openxyos_runtime.py
@@ -36,3 +36,21 @@ def test_stage_openxyos_runtime_from_sidecar_dir(tmp_path: Path) -> None:
     assert "openxyos/dist/index.html" in names
     assert "node/node.exe" in names
     assert "openxyos/backend/server.ts" in names
+    stage_mod.verify_runtime_zip(dest)
+    assert stage_mod.layout_ready(src)
+
+
+def test_readme_only_layout_cannot_ship(tmp_path: Path) -> None:
+    stub = tmp_path / "openxyos"
+    stub.mkdir()
+    (stub / "README.txt").write_text("FreeOS local openXYOS environment\n", encoding="utf-8")
+    assert stage_mod.layout_ready(stub) is False
+    empty_zip = tmp_path / "openxyos-runtime.zip"
+    with zipfile.ZipFile(empty_zip, "w") as zf:
+        zf.writestr("README.txt", "stub")
+    try:
+        stage_mod.verify_runtime_zip(empty_zip)
+    except SystemExit as exc:
+        assert "incomplete" in str(exc)
+    else:
+        raise AssertionError("README-only zip must not verify")
diff --git a/tests/unit/test_sidecar_launch.py b/tests/unit/test_sidecar_launch.py
index d02a18a3..1a90f1c1 100644
--- a/tests/unit/test_sidecar_launch.py
+++ b/tests/unit/test_sidecar_launch.py
@@ -117,6 +117,19 @@ def test_ensure_sidecar_skips_source_tree_script(
     assert spawned == []
 
 
+def test_bundle_rejects_readme_only_workdir(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    work = tmp_path / "openxyos-home"
+    work.mkdir()
+    (work / "README.txt").write_text("stub", encoding="utf-8")
+    monkeypatch.setenv("FREEOS_OPENXYOS_HOME", str(work))
+    monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "local"))
+    monkeypatch.delenv("OCTOP_GREEN_PACKAGES", raising=False)
+    monkeypatch.setenv("FREEOS_HOME", str(tmp_path / "unused-home"))
+    assert find_sidecar_runtime() is None
+
+
 def test_sidecar_bundle_dir_prefers_openxyos_home(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None: