Support live OpenGUI installation in WorkBuddy

README.md

@@ -83,9 +83,9 @@ Model availability, pricing, and policy behavior vary by version and region. Whi
 
 WorkBuddy has a separate [MCP + Skill + Hooks connector](./workbuddy-plugin/README.md#install-on-macos). It uses WorkBuddy's current visual model to operate Android phones and opens read-only scrcpy windows by default. No DSH installation, full OpenGUI backend, or extra model API key is required.
 
-Version `0.2.0` is a local candidate in [PR #95](https://github.com/Core-Mate/OpenGUI/pull/95), not a published Release or marketplace installation. Start with macOS and WorkBuddy 5.5.3; Windows/Linux package checks do not establish phone-control support. Follow the [macOS installation steps](./workbuddy-plugin/README.md#install-on-macos) to build the candidate and install its MCP, `opengui` Skill and lifecycle Hooks together. The installer preserves other plugins and backs up the affected WorkBuddy configuration.
+Version `0.3.1` is a macOS public-testing prerelease, not marketplace approval or complete real-device acceptance. It installs the MCP, `opengui` Skill and lifecycle Hooks together, preserves other plugins, and backs up the affected WorkBuddy configuration. WorkBuddy 5.5.6+ supports the live installation flow; older compatible versions use the Command-Q fallback reported by preflight.
 
-After restarting WorkBuddy, enable/trust the `opengui` MCP if prompted, connect a USB-debugging-authorized Android phone, select `/opengui`, and send:
+After installation, enable/trust the `opengui` MCP if prompted, review the external Hook change in `/hooks`, confirm `opengui` in `/skills`, connect a USB-debugging-authorized Android phone, select `/opengui`, and send:
 
 ```text
 Open Settings and report the Android version on my phone.

README.zh-CN.md

@@ -84,9 +84,9 @@ OpenGUI 正式支持 DSH `0.1.0-rc.7`、`0.1.0-rc.8`、`0.1.1-rc.1` 和 `0.1.1-r
 
 WorkBuddy 使用独立的 [MCP + Skill + Hooks 插件](./workbuddy-plugin/README.zh-CN.md#macos-安装)，由当前视觉模型看图操作 Android 手机，默认打开只读 scrcpy 投屏窗口。不需要安装 DSH、部署完整 OpenGUI 后端或额外配置模型 API Key。
 
-当前 `0.2.0` 是 [PR #95](https://github.com/Core-Mate/OpenGUI/pull/95) 中的本地候选版，尚未正式发布或上架市场。安装以 macOS、WorkBuddy 5.5.3 为基线，Windows/Linux 打包检查通过不代表支持真机操作。按照 [macOS 安装步骤](./workbuddy-plugin/README.zh-CN.md#macos-安装)，将 MCP、`opengui` 技能和生命周期 Hooks 一起安装。安装器会备份相关 WorkBuddy 配置，保留其他插件。
+当前 `0.3.1` 是 macOS 公测预发布版，不代表已经上架市场或完成全部真机验收。安装会把 MCP、`opengui` Skill 和生命周期 Hooks 一起配置，备份相关 WorkBuddy 配置并保留其他插件。WorkBuddy 5.5.6 及以上支持运行中安装；旧版兼容宿主会由预检明确要求 Command-Q。
 
-重开 WorkBuddy，按宿主提示启用并信任 `opengui` MCP，连接已授权 USB 调试的 Android 手机。在输入框选择 `/opengui`，发送：
+安装后按宿主提示启用并信任 `opengui` MCP，在 `/hooks` 中审查外部 Hook 变更，并在 `/skills` 中确认 `opengui`。连接已授权 USB 调试的 Android 手机，在输入框选择 `/opengui`，发送：
 
 ```text
 打开手机设置，查看并告诉我 Android 版本。

skills/opengui-plugin-install/SKILL.md

@@ -9,9 +9,9 @@ Infer Codex or WorkBuddy from the request; ask only if the target is missing. Th
 
 1. Read the public GitHub releases API for `Core-Mate/OpenGUI`, following pagination. Select the newest non-draft, non-prerelease semantic version with tag `opengui-codex-vX.Y.Z` or `opengui-workbuddy-vX.Y.Z` and all matching assets below. If the user explicitly asks for the public testing/prerelease version, include non-draft prereleases for that host and explain their uncompleted device acceptance. An explicit requested version takes precedence; never silently substitute a different version. Do not use the repository-wide latest release, which may be DSH or an APK.
 2. Download `opengui-HOST-X.Y.Z-install.command` and its `.sha256` asset from that release into a fresh temporary directory. Use HTTPS with redirect-to-HTTPS only. Require exact filenames and verify SHA-256 before executing the installer. The checksum establishes integrity relative to the selected public release, not an independent publisher signature.
-3. Finish existing OpenGUI tasks before an upgrade. WorkBuddy must be closed before its configuration can be changed; do not kill it or its phone/mirror processes. Codex requires the native CLI with `codex plugin` support. Never remove a conflicting plugin source without the user's authorization.
-4. For WorkBuddy, run the selected installer with `--check` first. Read its exact error code; do not inspect the entire application or rewrite configuration manually. Multiple applications require an explicit `--app` selection. If installing from within WorkBuddy itself, prepare the verified installer and give the user the single terminal command to run after Command-Q; do not repeatedly retry while the host is running. Normal installation uses the installer, not source checkout or agent-written JSON. Run `bash /absolute/path/opengui-HOST-X.Y.Z-install.command`. It downloads and verifies the matching package, prepares private Node 22.23.2, installs into a fresh version directory, and configures only the selected host. No Git clone, pnpm, source compilation, or user-run test suite is required.
-5. Read the result. On success, ask for a new Codex chat or a WorkBuddy restart, then verify read-only device discovery. USB and system permissions remain user actions. Installation success does not prove phone control, desktop visibility, or two-device acceptance.
+3. Finish existing OpenGUI phone tasks before an upgrade. WorkBuddy 5.5.6 or newer may stay open; never kill it or its phone/mirror processes. Older compatible WorkBuddy versions require a normal Command-Q restart when the installer reports `HOST_RESTART_REQUIRED`. Codex requires the native CLI with `codex plugin` support. Never remove a conflicting plugin source without the user's authorization.
+4. For WorkBuddy, run the selected installer with `--check` first. Read its exact error code; do not inspect the entire application or rewrite configuration manually. Multiple applications require an explicit `--app` selection. When invoked inside WorkBuddy 5.5.6+, run `bash /absolute/path/opengui-HOST-X.Y.Z-install.command` directly in the current task after the preflight passes. It downloads and verifies the matching package, prepares private Node 22.23.2, installs into a fresh version directory, and atomically configures only the selected host. If an upgrade reports `upgrade_blocked`, finish and close the old OpenGUI task/viewer/mirror, disable OpenGUI in MCP service management, wait for its broker to exit, then retry once. No Git clone, pnpm, source compilation, agent-written JSON, or user-run test suite is required.
+5. Read the result. After `LIVE_CONFIG_WRITTEN`, keep WorkBuddy open: trust/enable the OpenGUI MCP if prompted, open `/hooks` to review and apply the external Hook change, and open `/skills` to confirm `opengui`. Start a new task only if the current task does not refresh. After a stopped-host installation, open WorkBuddy and perform the same checks. Verify read-only device discovery before phone actions. USB and system permissions remain user actions. Installation success does not prove phone control, desktop visibility, or two-device acceptance.
 
 Required release assets:
 - Codex: `opengui-codex-X.Y.Z.tar.gz`, its `.sha256`, and the installer plus its `.sha256`.

workbuddy-plugin/CHANGELOG.md

@@ -1,3 +1,10 @@
+# OpenGUI for WorkBuddy 0.3.1 candidate
+
+- Allow WorkBuddy 5.5.6+ to stay open during a verified first installation or idle reconfiguration.
+- Use WorkBuddy's MCP file watcher, `/hooks` review flow, and `/skills` discovery instead of requiring Command-Q by default.
+- Keep older hosts on the restart path and block upgrades while an old OpenGUI broker still owns tasks or displays.
+- Preserve atomic configuration writes, unrelated MCP/Hooks, immutable packages, receipts, and rollback behavior.
+
 # OpenGUI for WorkBuddy 0.3.0 candidate
 
 - Add read-only H.264 video Viewers, visible first-frame gating, bounded reconnection and independent page/control lifecycles.

workbuddy-plugin/README.md

@@ -1,6 +1,6 @@
-# OpenGUI for WorkBuddy 0.3.0
+# OpenGUI for WorkBuddy 0.3.1
 
-[中文说明](README.zh-CN.md). macOS candidate, protocol 8. No public release or directory approval is implied by these files.
+[中文说明](README.zh-CN.md). macOS public-testing candidate, protocol 8. Marketplace approval and the remaining real-device gates are separate.
 
 OpenGUI opens real-time phone video beside the current chat using WorkBuddy built-in `present_files` with the Viewer URL and current working directory. A visible decoded H.264 frame must reach the backend before the first phone observation or action. An opening request or screenshot preview is insufficient. Video is read-only and local; model observations still use explicit screenshots.
 
@@ -18,12 +18,14 @@ After first display authorization, video failure or page closure does not cancel
 Use the supplied installer and matching archive with adjacent SHA-256 sidecars:
 
 ```sh
-bash scripts/install-macos.command --archive /absolute/path/opengui-mcp-0.3.0.tgz
+bash scripts/install-macos.command --archive /absolute/path/opengui-mcp-0.3.1.tgz
 ```
 
-The installer prepares private Node, verifies the package and scrcpy resources, and only then changes this host's configuration. Complete old phone tasks and close old displays before upgrading. No migration force-kills an old runtime. Repeated installation reuses verified caches; download failure reports its stage and leaves previous configuration available. Keep the old installer/archive and recovery record to reinstall the old version. The installer reports configuration, host loading and real-viewer acceptance separately.
+The installer prepares private Node, verifies the package and scrcpy resources, and only then changes this host's configuration. On WorkBuddy 5.5.6+, the application may stay open: MCP configuration is watched live, while external Hook changes are reviewed in `/hooks` and the installed Skill is confirmed in `/skills`. Start a new task only if the current task does not refresh. Older compatible hosts use the Command-Q fallback reported by preflight.
 
-WorkBuddy 5.5.3 domestic and overseas configuration discovery, running-host preflight, per-configuration receipts, and native Hooks are retained. Use `--check` or `--app /absolute/WorkBuddy.app` for explicit preflight. Legacy `opengui_start` and native mirror tools are compatibility-only, on explicit request. They never substitute for browser first-frame authorization.
+Complete old phone tasks and close old displays before upgrading. If an old broker remains, disable the old OpenGUI MCP and wait for its idle exit before retrying. No migration force-kills an old runtime. Repeated installation reuses verified caches; download failure reports its stage and leaves previous configuration available. Keep the old installer/archive and recovery record to reinstall the old version. The installer reports configuration, host loading and real-viewer acceptance separately.
+
+WorkBuddy 5.5.3 domestic and overseas configuration discovery, version-aware running-host preflight, per-configuration receipts, and native Hooks are retained. Use `--check` or `--app /absolute/WorkBuddy.app` for explicit preflight. Legacy `opengui_start` and native mirror tools are compatibility-only, on explicit request. They never substitute for browser first-frame authorization.
 
 ## Runtime and privacy
 

workbuddy-plugin/README.zh-CN.md

@@ -1,4 +1,4 @@
-# OpenGUI for WorkBuddy 0.3.0 候选版
+# OpenGUI for WorkBuddy 0.3.1 候选版
 
 本轮支持 macOS，协议版本 8。这是本地候选交付，不代表已公开发布或所有真机验收通过。
 
@@ -15,12 +15,14 @@ WorkBuddy 使用内置 present_files，传入 URL 与当前工作目录。国内
 核对安装器及归档旁的 SHA-256 文件，结束旧任务、关闭旧展示后运行：
 
 ```sh
-bash scripts/install-macos.command --archive /绝对路径/opengui-mcp-0.3.0.tgz
+bash scripts/install-macos.command --archive /绝对路径/opengui-mcp-0.3.1.tgz
 ```
 
-安装器自动准备独立 Node 与 scrcpy 资源，缓存完整时复用；准备失败保留旧配置，并输出恢复步骤。WorkBuddy 运行时会先要求退出一次；可用 --check 做只读预检，用 --app 指定国内或海外应用。
+安装器自动准备独立 Node 与 scrcpy 资源，缓存完整时复用；准备失败保留旧配置，并输出恢复步骤。WorkBuddy 5.5.6 及以上可以保持运行：MCP 配置由宿主实时监听，外部 Hook 变更在 `/hooks` 中审查应用，并在 `/skills` 中确认 `opengui`。当前任务没有刷新时再新建任务。旧版兼容宿主会由预检明确要求 Command-Q。可用 --check 做只读预检，用 --app 指定国内或海外应用。
 
-安装结果分别报告“配置完成”“宿主已加载”“设备墙可用”，写入配置不是验收通过。安装后在实际宿主选择 OpenGUI Skill，先检查只读设备发现，再验收右侧视频与截图操作。
+升级前仍需结束旧手机任务并关闭旧展示。如果旧 broker 仍在运行，先在 MCP 服务管理中停用旧 OpenGUI，等待其空闲退出后重试；安装器不会强杀 WorkBuddy 或手机进程。
+
+安装结果分别报告“热配置完成”“宿主已加载”“设备墙可用”，写入配置不是验收通过。安装后在实际宿主选择 OpenGUI Skill，先检查只读设备发现，再验收右侧视频与截图操作。
 
 ## 回退和验收
 

workbuddy-plugin/connector/connector-meta.json

@@ -7,7 +7,7 @@
   "description_en": "Control locally connected Android phones from WorkBuddy and monitor up to four phones in a read-only device wall.",
   "source": "opengui",
   "type": "mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "minWorkbuddyVersion": "5.5.3",
   "examples_zh": ["看看手机上的 Android 版本", "在设备墙里查看这两台手机的画面"],
   "examples_en": ["Check the Android version on my phone", "Show these two phones in the device wall"]

workbuddy-plugin/connector/mcp.json

@@ -6,7 +6,7 @@
       "args": [
         "--yes",
         "--prefer-offline",
-        "--package=https://github.com/Core-Mate/OpenGUI/releases/download/opengui-workbuddy-v0.3.0/opengui-mcp-0.3.0.tgz",
+        "--package=https://github.com/Core-Mate/OpenGUI/releases/download/opengui-workbuddy-v0.3.1/opengui-mcp-0.3.1.tgz",
         "opengui-mcp"
       ],
       "runtime": { "type": "node", "version": "^22.19.0 || >=24" },

workbuddy-plugin/connector/skills/control/SKILL.md

@@ -6,7 +6,7 @@ description: Autonomously complete user-authorized Android phone tasks using rea
 description_zh: 根据真实截图全自动完成用户指定的 Android 手机任务，默认持续投屏，自动恢复、核验结果并释放控制锁；不重复询问已授权步骤。
 description_en: Complete authorized Android tasks through a real VLM screenshot-action loop, persistent local displays, bounded recovery and automatic task cleanup.
 category: productivity
-version: 0.3.0
+version: 0.3.1
 author: OpenGUI
 ---
 

workbuddy-plugin/docs/release-notes.md

@@ -1,5 +1,7 @@
-# WorkBuddy 0.3.0 candidate
+# WorkBuddy 0.3.1 candidate
 
-Adds independent read-only real-time Viewers and first-visible-video authorization. Control completion preserves viewing; page closure preserves established control. Adds bounded H.264 recovery, native-host Skill routing, eager video-resource preparation, and upgrade checks. Protocol 8 rejects old runtimes; retain old packages and end old sessions/displays before switching. Existing observation safety and host isolation remain.
+Adds live installation for WorkBuddy 5.5.6 and newer. The host may stay open while the verified installer atomically writes the MCP, Skill, and Hook configuration. WorkBuddy watches the MCP file; the user reviews the external Hook change in `/hooks` and confirms the Skill in `/skills`. Older compatible hosts retain the Command-Q fallback.
 
-This candidate has not been published. See the candidate acceptance report for passed and outstanding gates. Do not equate source tests or a decoder capability check with installed-host real-device acceptance.
+Upgrades still stop if an old OpenGUI broker owns tasks or persistent displays. Finish those tasks, close their viewers or mirrors, disable the old OpenGUI MCP, and retry after the broker exits. The installer does not kill WorkBuddy or phone processes. Existing observation safety, host isolation, rollback receipts, and protocol 8 remain unchanged.
+
+This is a public-testing candidate. Stable publication still requires the gates in `release-readiness.json`.

workbuddy-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opengui-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Independent OpenGUI Android MCP runtime for WorkBuddy",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

workbuddy-plugin/release-readiness.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.0",
+  "version": "0.3.1",
   "checks": {
     "workbuddyImageToolFlow": {
       "verified": false,

workbuddy-plugin/scripts/install-local.mjs

@@ -26,7 +26,7 @@ const packagesRoot = await realpath(join(stateRoot, 'packages'))
 assert(!relative(packagesRoot, packageDir).startsWith('..') && relative(packagesRoot, packageDir), 'Install from an immutable WorkBuddy version directory')
 const pkg = JSON.parse(await readFile(join(packageDir, 'package.json'), 'utf8'))
 assert.equal(pkg.name, 'opengui-mcp')
-assert.equal(pkg.version, '0.3.0')
+assert.equal(pkg.version, '0.3.1')
 assert.match(execFileSync(node, ['--version'], { encoding: 'utf8' }).trim(), /^v(?:22\.(?:19|2\d|[3-9]\d)|2[4-9]\.|[3-9]\d\.)/)
 const quote = value => process.platform === 'win32' ? `'${value.replaceAll("'", "''")}'` : `'${value.replaceAll("'", `'"'"'`)}'`
 const command = `${quote(node)} ${quote(join(packageDir, 'lib', 'host-hook.js'))}`
@@ -75,7 +75,8 @@ for (let i = 0; i < targets.length; i++) {
   backups.push({ path, backup: original[i] === undefined ? null : backup, installedSha256: createHash('sha256').update(values[i]).digest('hex') })
 }
 // Prepare all bytes and the recovery journal before switching any entry.
-// A live client must be stopped by the caller; never overwrite concurrent edits.
+// WorkBuddy can watch these files live. Preserve the compare-before-rename checks
+// so a simultaneous host or user edit wins instead of being overwritten.
 if (await optional(installState)) await copyFile(installState, `${installState}.before-${stamp}`)
 await assertStatePath()
 const journal = `${installState}.pending-${stamp}`