codex-ringside 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.0 (2026-10-31)
+
+- Automatically check stable GitHub releases every six hours, verify and install newer standalone bundles, and retry failures after one hour. Preserve settings, back up and roll back failed updates without closing the desktop client.
+- Add `update`, `update --check`, `update --enable`, `update --disable` and update diagnostics in `status`; serialize updates with installation/uninstallation and cancel stale downloads.
+- Add a one-command macOS 13+ installer that verifies release checksums and selects native Apple Silicon or Intel bundles, including when Terminal runs under Rosetta.
+- Ship private Node 22.23.4 and precompiled Swift helpers so users do not need Node, Homebrew or Xcode Command Line Tools. LaunchAgents and the installed CLI use the private Node.
+- Preserve settings, migration backups and transactional rollback across standalone upgrades; uninstall removes the private runtime too.
+- Build/check standalone bundles on both macOS architectures in CI, publish both archives and the installer with checksums, and update English/Chinese installation and release documentation.
+
+## 0.1.1
+
+- Add copyable English and Chinese AI installation prompts to the README, covering prerequisites, installation, existing settings and status verification.
+- Present AI-assisted and terminal installation as separate options. Runtime behavior is unchanged.
+
 ## 0.1.0
 
 First stable public release. Includes all candidate features, with verified Codex Plus migration, preserved backgrounds and a single active renderer component on the development Mac.

package/README.md

@@ -12,46 +12,93 @@ See your remaining allowance at a glance, hover for reset times, and click a rin
 
 ## Install
 
-Requirements: macOS, Node.js 22+, Xcode Command Line Tools (`xcode-select --install`), and a signed-in compatible desktop client. The development host is `/Applications/ChatGPT.app`, version `26.1027.30824`, on Apple Silicon. Other host versions depend on compatible internal interfaces and are not individually verified. The CLI and settings panel currently use Chinese labels.
+One-command installation requires **macOS 13+** (Apple Silicon or Intel) and a signed-in compatible desktop client. **You do not need Node.js, npm, Homebrew or Xcode Command Line Tools.** The release includes a private Node runtime and a precompiled helper. The development host is `/Applications/ChatGPT.app`, version `26.1027.30824`; other host versions depend on compatible internal interfaces. CLI and panel labels currently use Chinese.
+
+### Option 1: One-command install (recommended)
+
+Paste into Terminal:
 
 ```bash
-npx codex-ringside@latest install
+curl -fsSL https://github.com/tccpc/codex-ringside/releases/latest/download/install.sh | /bin/bash
 ```
 
+Available starting with release **0.2.0**. The script selects your native architecture (including Apple Silicon terminals running under Rosetta), downloads a release bundle over HTTPS, checks its SHA-256, and installs under your user account. It does not use or change your system Node, shell configuration or Homebrew installation; no `sudo` is required. The background task also uses the private runtime. Installation leaves an already-open desktop session running.
+
 If rings do not appear, save your work, quit the desktop app with ⌘Q, and reopen its original icon. The add-on may reopen a freshly launched client once, subject to the safeguards below.
 
-Observe mode installs the agent without allowing it to restart the desktop client:
+Observe mode disables that startup handoff:
+
+```bash
+curl -fsSL https://github.com/tccpc/codex-ringside/releases/latest/download/install.sh | /bin/bash -s -- --observe
+```
+
+To inspect the installer before running it, download `install.sh` from [Releases](https://github.com/tccpc/codex-ringside/releases), read it, then run `/bin/bash install.sh`. Use `--version 0.2.0` to select an exact release. To set a custom host path, export it before running the one-command installer:
 
 ```bash
-npx codex-ringside@latest install --observe
+export CODEX_RINGSIDE_APP="/Applications/ChatGPT.app"
 ```
 
-You can also use `npm install -g codex-ringside`, then `codex-ringside install`. Downloading the npm package alone never installs or starts the agent: there are no install lifecycle hooks. No `sudo` is needed with npx.
+After installation, status and uninstall work without npm:
+
+```bash
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" uninstall
+```
+
+### Option 2: Ask an AI assistant
+
+Copy this prompt into an assistant that can run commands on your Mac:
+
+```text
+Please install Codex Ringside on my Mac: https://github.com/tccpc/codex-ringside
+Read the README and explain what will be installed, including the local debug port.
+Check macOS 13+ and a compatible signed-in desktop client. If unsupported, stop.
+Use the README's one-command installer. It bundles Node and the helper; do not install Homebrew, Node or Xcode tools for this task.
+Preserve existing settings. If the app is outside the default location, export CODEX_RINGSIDE_APP with its detected path.
+After installation, run "$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status.
+Report whether the agent is running and the ring is placed, and give the uninstall command.
+If needed, ask me to save my work and reopen the client manually. Do not close or force-quit it.
+```
+
+### Option 3: npm / source installation
+
+For developers who already have **Node.js 22+ and Xcode Command Line Tools**:
+
+```bash
+npx codex-ringside@latest install
+```
+
+This path compiles the Swift helper locally. It requires a working system Node; if `npx` crashes with a missing Homebrew dynamic library, use Option 1. Downloading the npm package alone never installs or starts the agent: there are no install lifecycle hooks. npm users can continue using `npx codex-ringside@latest <command>` for status, background settings and uninstall.
 
 | Location | Contents |
 | --- | --- |
-| `~/Library/Application Support/CodexRingside` | Runtime, locally compiled bridge, settings and state |
+| `~/Library/Application Support/CodexRingside` | Program, private Node and its license (one-command install), helper, settings and state |
 | `~/Library/LaunchAgents/com.codexringside.agent.plist` | Background agent |
 | `~/Library/Logs/CodexRingside` | Agent logs |
 | `~/Library/Application Support/CodexRingside Backups` | Local installation/migration backups |
 
-The installed runtime is independent of the checkout. For a custom application path:
+Host resolution order: `CODEX_RINGSIDE_APP`, legacy `CODEX_PLUS_APP`, saved path, then `/Applications/ChatGPT.app`.
 
-```bash
-CODEX_RINGSIDE_APP="/Applications/ChatGPT.app" npx codex-ringside@latest install
-```
+## Upgrade and migrate from Codex Plus
 
-Resolution order: `CODEX_RINGSIDE_APP`, legacy `CODEX_PLUS_APP`, saved path, then `/Applications/ChatGPT.app`.
+**Automatic updates are enabled by default.** About one minute after the agent starts, it checks the latest stable GitHub Release, then checks every six hours. Check times survive restarts. A newer release is downloaded for the running architecture, verified against its SHA-256 manifest, checked for the expected version/runtime, and installed with its private Node. Drafts, prereleases and downgrades are skipped. Failed checks or installations retry after one hour.
 
-## Upgrade and migrate from Codex Plus
+An independent update job restarts only the Ringside agent, leaving the desktop session open. The app path, observe mode, background, images and update preference are preserved. Files are backed up before replacement; if the new watcher fails to become ready, the installer restores previous files, runtime and service state. Uninstalling, reinstalling or disabling updates during a download cancels that automatic installation. A lock prevents overlapping installation, update replacement and uninstall operations.
+
+```bash
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --check
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --disable
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --enable
+```
 
-Run `npx codex-ringside@latest install` again. Existing Ringside settings take precedence. First migration preserves the old application path, observe mode, background settings and images, then retires `com.codexplus.agent`.
+These commands update immediately, check only, disable or enable automatic updates. `status` includes an `update` object with the installed/latest versions, preference, check times and last error; timestamps are Unix milliseconds. Update logs are in `~/Library/Logs/CodexRingside/update.log` and `update.err.log`. A version-pinned install still follows future stable releases; disable automatic updates to keep a pinned version or source changes.
 
-The helper is compiled in a staging directory before services are stopped. Files are backed up before replacement; if the new watcher fails to become ready, the installer restores previous files and service state. A lock prevents overlapping install/uninstall operations. Installation itself does not restart an existing desktop session.
+Older versions need one manual reinstall to receive this feature. Existing Ringside settings take precedence over Codex Plus settings; first migration preserves the old settings and retires `com.codexplus.agent`.
 
 Backups remain in `CodexRingside Backups/install-*`. `receipt.json` records original paths and service states; `0` contains the previous Ringside installation and `1` the previous Codex Plus installation. Backups can contain private paths and images. Keep them local and remove them manually when satisfied with the upgrade. Uninstall preserves backups.
 
-Reinstalling preserves observe mode; `install --observe` explicitly disables startup handoff. To re-enable it, unload the agent, set `allowClientRestart` to `true` in the installed `settings.json`, then run `install` again.
+Reinstalling preserves observe mode; `--observe` explicitly disables startup handoff. To re-enable it, unload the agent, set `allowClientRestart` to `true` in the installed `settings.json`, then reinstall. npm/source users can use `npx codex-ringside@latest update`; a successful update switches the managed installation to the standalone bundle with private Node, without changing the source checkout. `npx codex-ringside@latest install` continues to require development tools.
 
 ## Background controls
 
@@ -69,10 +116,10 @@ Transparency and blur control the effect. Images support cover, contain, stretch
 The appearance switch uses the host's own system/light/dark setting and synchronizes with its settings page. It is hidden when compatible internal functions cannot be found.
 
 ```bash
-npx codex-ringside@latest background image ~/Pictures/photo.jpg --transparency 50 --blur 8
-npx codex-ringside@latest background --layout contain --zoom 120 --y 20
-npx codex-ringside@latest background --crop 10,0,80,60
-npx codex-ringside@latest background default
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background image ~/Pictures/photo.jpg --transparency 50 --blur 8
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background --layout contain --zoom 120 --y 20
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background --crop 10,0,80,60
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background default
 ```
 
 Options without a source keep the current source. `background` without arguments prints the saved configuration. Crop values are left, top, width and height in percentages; `--crop none` clears the crop. `--help` lists flags and `--version` prints the version; both work without an installed host.
@@ -88,12 +135,12 @@ Options without a source keep the current source. `background` without arguments
 ## Status and troubleshooting
 
 ```bash
-npx codex-ringside@latest status
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
 ```
 
 Look for `agent: "running"`, `cdp.windows[].card.placed`, and `cdp.windows[].background.applied`. `nativeGlass: false` means the host disables native glass. `startup.event` explains skipped handoffs. Status may contain private paths and window URLs; redact it before sharing.
 
-If no ring appears, verify the signed-in host, application path, Node version, Command Line Tools and whether port 39222 is occupied. Installing while the host is open does not trigger a restart. Save your work and reopen its original icon when convenient. Check `~/Library/Logs/CodexRingside` for errors.
+If no ring appears, verify the signed-in host, application path and whether port 39222 is occupied. Node and Command Line Tools checks apply only to npm/source installations. A missing release asset means that version does not contain a standalone bundle; use 0.2.0 or later. A checksum or download failure stops before changing the installed app; retry when the network is available. Installing while the host is open does not trigger a restart. Save your work and reopen its original icon when convenient. Check `~/Library/Logs/CodexRingside` for errors.
 
 Missing or expired allowance data is shown as unavailable. Account switches reset the app-server connection. The number of rings follows the valid allowance windows returned for your account.
 
@@ -106,10 +153,10 @@ An app already running when the agent starts is never handed off. Only normal sy
 ## Uninstall
 
 ```bash
-npx codex-ringside@latest uninstall
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" uninstall
 ```
 
-This removes current and legacy agents, moves runtime/settings/logs to the Trash and removes injected UI. Backups remain. The desktop application bundle is unchanged. The debug port remains active until that desktop process exits; the next ordinary launch has no Ringside debug flag.
+This removes current and legacy agents and the update job, moves the private Node runtime and program/settings/logs to the Trash and removes injected UI. Backups remain. The desktop application bundle is unchanged. The debug port remains active until that desktop process exits; the next ordinary launch has no Ringside debug flag.
 
 ## Security and privacy
 
@@ -117,7 +164,7 @@ Ringside starts the host's bundled `codex app-server`, reads `account/rateLimits
 
 **The debug endpoint has no authentication.** Local software can execute JavaScript in the desktop renderer through it. Never expose, forward or proxy port 39222. Use this add-on only where you trust the other local software.
 
-Ringside does not read project files, chat content or the conversation database, and has no telemetry. It checks only the modification time of `auth.json`. The host CLI makes its own network requests. Wallpaper and chosen image processing is local; images/configuration are not uploaded. See [SECURITY.md](SECURITY.md).
+Ringside does not read project files, chat content or the conversation database, and has no telemetry. It checks only the modification time of `auth.json`. The host CLI makes its own network requests. Automatic updates request the public GitHub release API and assets without account tokens or local settings, paths or images; `update --disable` stops automatic requests. Wallpaper and chosen image processing is local; images/configuration are not uploaded. See [SECURITY.md](SECURITY.md).
 
 ## Development
 
@@ -128,7 +175,7 @@ npm ci --ignore-scripts
 npm run verify
 ```
 
-Verification runs syntax checks, unit tests and tests the actual packed CLI and Swift source. There are no runtime npm dependencies. CI covers Node.js 22/24/26 and compiles on Apple Silicon and Intel macOS. Full host compatibility requires a real signed-in client.
+Development requires Node.js 22+ and Xcode Command Line Tools. Verification runs syntax checks, unit tests and tests the actual packed CLI and Swift source. `npm run build:standalone` builds a native release bundle; `npm run check:standalone` tests its real runtime, helper, installation and rollback with simulated services and unusable system development tools. There are no runtime npm dependencies. CI covers Node.js 22/24/26 and compiles on Apple Silicon and Intel macOS. Full host compatibility requires a real signed-in client.
 
 For the browser-only fixture, run `python3 -m http.server 4173 --bind 127.0.0.1` from the checkout and open `http://127.0.0.1:4173/test/fixtures/card.html`. It uses simulated data and gradient images.
 

package/README.zh-CN.md

@@ -19,47 +19,95 @@
 
 ## 安装
 
-需要 macOS、Node.js 22+ 和 Xcode Command Line Tools（`xcode-select --install`），以及已登录的兼容桌面客户端。开发与真机验证使用 `/Applications/ChatGPT.app`，版本 `26.1027.30824`。其他客户端版本依赖相同内部结构，未逐一验证。
+一键安装需要 **macOS 13 或更高版本**（Apple Silicon 或 Intel），以及已登录的兼容桌面客户端。**无需自行安装 Node.js、npm、Homebrew 或 Xcode Command Line Tools。** 安装包自带专用 Node 和预编译 helper。开发验证使用 `/Applications/ChatGPT.app`，版本 `26.1027.30824`；其他客户端版本依赖相同内部结构，未逐一验证。命令行和设置面板目前使用中文。
 
-以下命令显式安装后台任务；仅下载 npm 包不会安装或启动后台。命令行和设置面板目前使用中文。
+### 方式一：一键安装（推荐）
+
+在终端粘贴这一条命令：
 
 ```bash
-npx codex-ringside@latest install
+curl -fsSL https://github.com/tccpc/codex-ringside/releases/latest/download/install.sh | /bin/bash
+```
+
+从 **0.2.0** 版本开始提供。脚本自动识别芯片架构（包括 Rosetta 下的终端），通过 HTTPS 下载对应安装包，校验 SHA-256 后安装到当前用户目录。安装和后台运行均使用插件自带的 Node，不依赖或更改系统 Node、Homebrew、终端配置，也不需要 `sudo`。安装过程不会关闭正在使用的客户端。
+
+如果圆环还没出现，保存工作，用 ⌘Q 退出客户端，再点原图标打开。后台可能在符合下文条件时将刚启动的客户端重开一次。
+
+只观察、不自动重开客户端：
+
+```bash
+curl -fsSL https://github.com/tccpc/codex-ringside/releases/latest/download/install.sh | /bin/bash -s -- --observe
+```
+
+想先审阅脚本，可以从 [Releases](https://github.com/tccpc/codex-ringside/releases) 下载 `install.sh`，阅读后执行 `/bin/bash install.sh`。加上 `--version 0.2.0` 可指定发行版本。应用不在默认位置时，先设置路径，再执行一键安装命令：
+
+```bash
+export CODEX_RINGSIDE_APP="/Applications/ChatGPT.app"
+```
+
+安装后查看状态和卸载也不需要 npm：
+
+```bash
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" uninstall
+```
+
+### 方式二：让 AI 帮你安装
+
+把下面整段提示词复制给能在你的 Mac 上运行命令的 AI 助手：
+
+```text
+请帮我在这台 Mac 上安装 Codex Ringside：https://github.com/tccpc/codex-ringside
+先阅读 README，说明安装内容和本机调试端口的用途。
+检查 macOS 13+ 和已登录的兼容客户端，不支持时停止。
+使用 README 的一键安装入口；安装包自带 Node 和 helper，不要为此安装 Homebrew、Node 或 Xcode 命令行工具。
+保留已有设置；应用不在默认位置时，先 export CODEX_RINGSIDE_APP 为检测到的路径。
+安装后运行："$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
+告诉我后台是否正常、圆环是否显示，并给出卸载命令。
+需要重开客户端时提醒我保存工作后手动操作，不要主动关闭或强制结束客户端。
 ```
 
-然后保存工作，用 ⌘Q 退出 Codex，再点原图标打开。
+### 方式三：npm / 源码安装
 
-只想看后台会做什么、不重启 Codex：
+适用于已有 **Node.js 22+ 和 Xcode Command Line Tools** 的开发者：
 
 ```bash
-npx codex-ringside@latest install --observe
+npx codex-ringside@latest install
 ```
 
-安装内容：
+此方式在本机编译 Swift helper，需要本机 Node 能正常运行。如果 `npx` 因 Homebrew 动态库缺失崩溃，直接使用方式一。仅下载 npm 包不会安装或启动后台；没有安装生命周期脚本。npm 用户仍可使用 `npx codex-ringside@latest <命令>` 查看状态、设置背景和卸载。
 
 | 位置 | 内容 |
 |---|---|
-| `~/Library/Application Support/CodexRingside` | 程序、`bridge`、设置和状态 |
+| `~/Library/Application Support/CodexRingside` | 程序、专用 Node 及许可证（一键安装）、helper、设置和状态 |
 | `~/Library/LaunchAgents/com.codexringside.agent.plist` | 后台任务 |
 | `~/Library/Logs/CodexRingside` | 日志 |
+| `~/Library/Application Support/CodexRingside Backups` | 安装和迁移备份 |
 
-运行时不依赖这个仓库，改代码后要重新 `install`。
+应用路径按 `CODEX_RINGSIDE_APP`、旧变量 `CODEX_PLUS_APP`、保存的应用路径、默认 `/Applications/ChatGPT.app` 的顺序选择。
 
 ## 升级和从 Codex Plus 迁移
 
-升级时重新运行 `npx codex-ringside@latest install`。已有新版设置优先；首次迁移保留旧版应用路径、观察模式、背景设置和图片，并停用 `com.codexplus.agent`。先暂存编译、备份，再切换后台；新后台未就绪时恢复原文件和运行状态。
-
-备份保留在 `~/Library/Application Support/CodexRingside Backups/install-*`。`receipt.json` 记录原路径及后台运行状态，`0` 是原 Ringside 安装，`1` 是原 Codex Plus 安装。卸载不会删除备份，确认新版正常后可手动清理。
+从本版起，**自动更新默认开启**。后台启动约一分钟后检查 GitHub 的最新正式发行版，之后每 6 小时检查一次；检查时间会保存，重启后台不会重复下载。发现更高版本后，自动下载对应架构的完整安装包，校验 SHA-256、版本及运行时，再升级程序和专用 Node。跳过草稿和预发行版，不会降级。网络或安装失败会记录原因，一小时后重试。
 
-迁移和重装保留观察模式；`install --observe` 可明确关闭自动接管。要重新开启，退出后台后将安装目录 `settings.json` 的 `allowClientRestart` 改为 `true`，再运行 `install`。备份包含本地路径及图片，不要上传。
+更新由独立任务执行，只重启插件后台，不关闭正在使用的客户端。现有应用路径、观察模式、背景、图片和自动更新开关都会保留；新后台未就绪时恢复原文件、运行时和运行状态。下载期间卸载、重新安装或关闭自动更新，会取消这次自动安装。
 
-非默认应用路径：
+也可以立即更新、只检查或控制自动更新：
 
 ```bash
-CODEX_RINGSIDE_APP="/Applications/ChatGPT.app" npx codex-ringside@latest install
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --check
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --disable
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" update --enable
 ```
 
-新环境变量优先于旧变量 `CODEX_PLUS_APP`，然后使用保存的应用路径，最后使用默认 `/Applications/ChatGPT.app`。
+`status` 的 `update` 字段显示当前/最新版本、自动更新开关、检查时间、下次检查时间和失败原因；时间字段为 Unix 毫秒时间戳。更新日志在 `~/Library/Logs/CodexRingside/update.log` 和 `update.err.log`。指定版本安装后仍会跟随正式版；需要固定版本或保留源码改动时，运行 `update --disable`。
+
+旧版用户先重新执行一次一键安装命令，获得自动更新功能。已有新版设置优先；首次从 Codex Plus 迁移会保留旧版设置，并停用 `com.codexplus.agent`。安装、更新切换和卸载共用互斥锁，不会互相覆盖。
+
+备份保留在 `~/Library/Application Support/CodexRingside Backups/install-*`。`receipt.json` 记录原路径及后台运行状态，`0` 是原 Ringside 安装，`1` 是原 Codex Plus 安装。卸载不会删除备份，确认新版正常后可手动清理。
+
+迁移和重装保留观察模式；`--observe` 可明确关闭自动接管。要重新开启，退出后台后将安装目录 `settings.json` 的 `allowClientRestart` 改为 `true`，再重新安装。备份包含本地路径及图片，不要上传。npm / 源码用户可用 `npx codex-ringside@latest update` 执行相同更新；更新成功后，已安装副本转为包含专用 Node 的独立安装，不修改源码工作区。继续用 `npx codex-ringside@latest install` 则仍需开发工具。
 
 ## 自定义背景
 
@@ -90,22 +138,22 @@ CODEX_RINGSIDE_APP="/Applications/ChatGPT.app" npx codex-ringside@latest install
 也可以用命令行设置，5 秒内生效：
 
 ```bash
-npx codex-ringside@latest background image ~/Pictures/photo.jpg --transparency 50 --blur 8
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background image ~/Pictures/photo.jpg --transparency 50 --blur 8
 ```
 
 ```bash
-npx codex-ringside@latest background --layout contain --zoom 120 --y 20
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background --layout contain --zoom 120 --y 20
 ```
 
 ```bash
-npx codex-ringside@latest background --crop 10,0,80,60
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background --crop 10,0,80,60
 ```
 
 ```bash
-npx codex-ringside@latest background default
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" background default
 ```
 
-只写选项时保留当前来源，不带参数时打印当前设置。`--crop` 的四个数是左、上、宽、高的百分比，`--crop none` 取消裁剪。完整选项见不带参数运行 `npx codex-ringside@latest` 的用法提示。
+只写选项时保留当前来源，不带参数时打印当前设置。`--crop` 的四个数是左、上、宽、高的百分比，`--crop none` 取消裁剪。完整选项见不带参数运行安装目录内的 `bin/codex-ringside` 的用法提示。
 
 使用限制：
 
@@ -117,8 +165,10 @@ npx codex-ringside@latest background default
 
 ## 查看状态
 
+下载失败或 SHA-256 校验失败时，安装器会在更改现有安装前停止，可在网络恢复后重试。发行版缺少安装包时，请选择 0.2.0 或更高版本。通过一键入口安装后，无需检查系统 Node 或编译工具。
+
 ```bash
-npx codex-ringside@latest status
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" status
 ```
 
 重点看 `cdp.windows[].card.placed`。背景看 `background`（保存的设置）和 `cdp.windows[].background`：`applied` 表示已生效，`nativeGlass` 为 `false` 表示 Codex 此刻关闭了毛玻璃。输出可能包含本机路径，分享前请先脱敏。
@@ -126,10 +176,10 @@ npx codex-ringside@latest status
 ## 卸载
 
 ```bash
-npx codex-ringside@latest uninstall
+"$HOME/Library/Application Support/CodexRingside/bin/codex-ringside" uninstall
 ```
 
-新旧后台任务会被移除，程序、设置和日志进废纸篓，安装备份保留。当前窗口的注入界面会移除；调试端口会保持到客户端退出，下次正常启动后关闭。桌面应用文件未改动。
+新旧后台任务和自动更新任务会被移除，专用 Node 随程序一起卸载，程序、设置和日志进废纸篓，安装备份保留。当前窗口的注入界面会移除；调试端口会保持到客户端退出，下次正常启动后关闭。桌面应用文件未改动。
 
 ## 什么时候会重启 Codex
 
@@ -152,15 +202,19 @@ npx codex-ringside@latest uninstall
 
 ## 隐私
 
-只读取额度数据，不读项目文件、对话内容和 Codex 数据库，也没有任何上报。`auth.json` 只看修改时间，用来发现账号切换，不读内容。app-server 自身的网络请求由 Codex CLI 发出。背景功能只读取系统壁纸和你选的图片，转换后存在本机的 `CodexRingside/background` 目录，不会上传。
+只读取额度数据，不读项目文件、对话内容和 Codex 数据库，也没有遥测或数据上传。`auth.json` 只看修改时间，用来发现账号切换，不读内容。app-server 自身的网络请求由 Codex CLI 发出。自动更新会请求 GitHub 的公开发行接口并下载发行包，不使用账号令牌，不发送本机设置、路径或图片；可以用 `update --disable` 关闭自动请求。背景功能只读取系统壁纸和你选的图片，转换后存在本机的 `CodexRingside/background` 目录，不会上传。
 
 ## 开发
 
+开发和源码构建仍需要 Node.js 22+ 与 Xcode Command Line Tools。一键安装的普通用户不需要这些工具。
+
 ```bash
 npm ci --ignore-scripts
 npm run verify
 ```
 
+`npm run build:standalone` 构建本机架构的完整安装包，`npm run check:standalone` 使用包内真实 Node 和 helper，在系统开发工具不可用的隔离环境下验证安装、重装和回滚。CI 分别在 Apple Silicon 与 Intel 上运行此检查。
+
 卡片样式可以用 `test/fixtures/card.html` 调试，不需要真实的 Codex。
 
 完整开发和发布流程见 [贡献指南](CONTRIBUTING.md)、[发布指南](docs/RELEASING.md)；漏洞请通过 [私密安全报告](https://github.com/tccpc/codex-ringside/security/advisories/new) 提交。

package/bin/codex-ringside.cjs

@@ -7,6 +7,7 @@ const { BackgroundStore, parseBackgroundArgs } = require('../src/background.cjs'
 const { CDP_PORT, CdpSession, isMainWindow, listTargets } = require('../src/cdp.cjs');
 const launchd = require('../src/launchd.cjs');
 const installer = require('../src/install.cjs');
+const updater = require('../src/update.cjs');
 const { version } = require('../package.json');
 
 const { installDir } = launchd.paths;
@@ -28,6 +29,7 @@ async function install({ observe }) {
     ? '如果圆环还没出现：保存工作后用 ⌘Q 退出 Codex，再点原图标打开。'
     : '当前为观察模式：不会重启 Codex。');
   console.log(`原安装备份：${result.backup}`);
+  console.log(result.settings.autoUpdate ? '自动更新已开启，每 6 小时检查正式发行版。' : '自动更新已关闭。');
 }
 
 // Reachable only if Codex is running with the port; without it there is no card to remove.
@@ -86,6 +88,7 @@ async function status() {
   console.log(JSON.stringify({
     agent: job ? job.match(/state = (\S+)/)?.[1] ?? 'loaded' : 'not installed',
     settings: readJson(settingsFile),
+    update: fs.existsSync(settingsFile) ? updater.updateStatus(installDir) : null,
     background: new BackgroundStore({ root: installDir }).config,
     startup: state && { event: state.event, updatedAt: new Date(state.updatedAt).toISOString() },
     listenAddresses: listeners(),
@@ -105,6 +108,23 @@ async function background(args) {
   console.log(`背景来源：${config.source}，5 秒内生效。`);
 }
 
+async function update(args) {
+  if (args.length > 1 || args.some(arg => !['--check', '--enable', '--disable'].includes(arg))) {
+    throw Error('用法：codex-ringside update [--check | --enable | --disable]');
+  }
+  if (args[0] === '--enable' || args[0] === '--disable') {
+    const enabled = args[0] === '--enable';
+    await updater.setAutoUpdate(enabled);
+    console.log(enabled ? '自动更新已开启，后台将在一分钟内检查。' : '自动更新已关闭。');
+    return;
+  }
+  console.log('正在检查 GitHub 正式发行版…');
+  const result = await updater.runUpdate({ checkOnly: args[0] === '--check' });
+  if (result.status === 'updated') console.log(`已更新到 ${result.installedVersion}，后台已重启。`);
+  else if (result.status === 'available') console.log(`发现新版本 ${result.latestVersion}。`);
+  else console.log('当前没有更新的正式版本。');
+}
+
 async function main() {
   const [command, ...args] = process.argv.slice(2);
   if (command === '--version' || command === '-v') { console.log(version); return; }
@@ -116,8 +136,10 @@ async function main() {
   else if (command === 'uninstall') await uninstall();
   else if (command === 'status') await status();
   else if (command === 'background') await background(args);
+  else if (command === 'update') await update(args);
   else {
-    console.log('用法：codex-ringside <install [--observe] | uninstall | status | background [来源] [选项]>');
+    console.log('用法：codex-ringside <install [--observe] | uninstall | status | update [选项] | background [来源] [选项]>');
+    console.log('更新选项：--check 仅检查 | --enable 开启自动更新 | --disable 关闭自动更新；无选项立即更新');
     console.log('背景来源：default | image <图片路径> | wallpaper | glass');
     console.log('背景效果：--transparency <0-100> --blur <0-60>');
     console.log('图片调整：--layout <cover|contain|stretch|center|tile> --zoom <10-400> --x <0-100> --y <0-100>');

package/native/bridge.swift

@@ -155,6 +155,10 @@ func wallpaper() -> [String: Any] {
 }
 
 let args = CommandLine.arguments
+if args.count == 2 && args[1] == "version" {
+    emit(["protocol": 1])
+    exit(0)
+}
 guard args.count >= 3 else { fail("usage: bridge <command> <app> [...]") }
 let command = args[1]
 let appPath = canonical(args[2])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-ringside",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Usage rings and customizable backgrounds for the Codex desktop app. Unofficial macOS add-on.",
   "license": "MIT",
   "type": "commonjs",
@@ -20,7 +20,9 @@
     "status": "node bin/codex-ringside.cjs status",
     "check": "node scripts/check.cjs",
     "check:package": "node scripts/check-package.cjs",
-    "verify": "npm run check && npm test && npm run check:package"
+    "verify": "npm run check && npm test && npm run check:package",
+    "build:standalone": "node scripts/build-standalone.cjs",
+    "check:standalone": "node scripts/check-standalone.cjs"
   },
   "repository": {
     "type": "git",

package/src/agent.cjs

@@ -151,6 +151,7 @@ function loadSettings(root) {
 
 async function main() {
   const { startWatcher } = require('./startup/watch.cjs');
+  const { startAutoUpdater } = require('./update.cjs');
   const root = path.resolve(__dirname, '..');
   const settings = loadSettings(root);
   const abort = new AbortController();
@@ -165,6 +166,7 @@ async function main() {
   process.once('SIGINT', shutdown);
   process.once('SIGTERM', shutdown);
 
+  startAutoUpdater({ root, signal: abort.signal, log });
   await runAgent({ appPath: settings.app, root, signal: abort.signal });
   await watcher.exited;
 }

package/src/install.cjs

@@ -5,6 +5,7 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const launchd = require('./launchd.cjs');
 const { DEFAULT_APP, isExecutable, resolveCodexBin, resolveNode } = require('./resolve.cjs');
+const { inspectBundle, copyBundle } = require('./standalone.cjs');
 
 const SWIFTC = '/usr/bin/swiftc';
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
@@ -29,10 +30,12 @@ function writeJson(file, data) {
   fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
 }
 
-function preflight(settings) {
+function preflight(settings, repoRoot, current) {
   if (process.platform !== 'darwin') throw new Error('只支持 macOS');
   const app = fs.realpathSync(settings.app);
   resolveCodexBin(app);
+  const bundle = inspectBundle(repoRoot);
+  if (bundle) return { app, node: path.join(current.installDir, 'runtime/node'), bundle };
   if (!isExecutable(SWIFTC)) throw new Error('需要 Xcode Command Line Tools：xcode-select --install');
   return { app, node: resolveNode() };
 }
@@ -98,12 +101,13 @@ function selectSettings(current, legacy, env, observe) {
     ?? readJson(path.join(legacy.installDir, 'settings.json')) ?? {};
   return {
     app: env.CODEX_RINGSIDE_APP || env.CODEX_PLUS_APP || saved.app || DEFAULT_APP,
-    allowClientRestart: observe === undefined ? saved.allowClientRestart !== false : !observe
+    allowClientRestart: observe === undefined ? saved.allowClientRestart !== false : !observe,
+    autoUpdate: saved.autoUpdate !== false
   };
 }
 
 function copyUserData(source, stage, destination) {
-  for (const name of ['background.json', 'background', 'user-images']) {
+  for (const name of ['background.json', 'background', 'user-images', 'update-state.json']) {
     copyIfPresent(path.join(source, name), path.join(stage, name));
   }
   const file = path.join(stage, 'background.json');
@@ -123,8 +127,10 @@ function copyUserData(source, stage, destination) {
 async function install(options = {}) {
   const { current, legacy, backupRoot, repoRoot, services } = { ...defaults, ...options };
   return withLock(current, async () => {
+    // Recheck under the install lock: an update downloaded before uninstall/reinstall is stale.
+    options.beforeInstall?.();
     const settings = selectSettings(current, legacy, options.env ?? process.env, options.observe);
-    const checked = await (options.preflight ?? preflight)(settings);
+    const checked = await (options.preflight ?? preflight)(settings, repoRoot, current);
     settings.app = checked.app;
     const stage = fs.mkdtempSync(`${current.installDir}.staging-`);
     const locations = [current, legacy];
@@ -134,8 +140,13 @@ async function install(options = {}) {
     let touched = false;
     try {
       fs.cpSync(path.join(repoRoot, 'src'), path.join(stage, 'src'), { recursive: true });
+      fs.mkdirSync(path.join(stage, 'bin'));
+      fs.copyFileSync(path.join(repoRoot, 'bin/codex-ringside.cjs'), path.join(stage, 'bin/codex-ringside.cjs'));
+      if (checked.bundle) fs.copyFileSync(path.join(repoRoot, 'bin/codex-ringside'), path.join(stage, 'bin/codex-ringside'));
       for (const name of ['package.json', 'LICENSE', 'NOTICE']) fs.copyFileSync(path.join(repoRoot, name), path.join(stage, name));
-      await (options.compile ?? compile)(repoRoot, stage);
+      if (checked.bundle) copyBundle(repoRoot, stage);
+      else await (options.compile ?? compile)(repoRoot, stage);
+      options.beforeInstall?.();
       fs.mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
       backup = fs.mkdtempSync(path.join(backupRoot, 'install-'));
       snapshots = capture(locations, backup);
@@ -194,6 +205,7 @@ async function install(options = {}) {
 async function uninstall(options = {}) {
   const { current, legacy, trashRoot, services } = { ...defaults, ...options };
   return withLock(current, async () => {
+    await services.bootout(launchd.UPDATE_LABEL);
     const locations = [current, legacy];
     const running = locations.map(location => !!services.printJob(location.label));
     const items = locations.flatMap((location, i) => launchd.trashItems(location)
@@ -219,4 +231,4 @@ async function uninstall(options = {}) {
   });
 }
 
-module.exports = { install, uninstall, selectSettings };
+module.exports = { install, uninstall, selectSettings, withLock };

package/src/launchd.cjs

@@ -5,6 +5,7 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 
 const LABEL = 'com.codexringside.agent';
+const UPDATE_LABEL = 'com.codexringside.update';
 const home = os.homedir();
 const paths = {
   installDir: path.join(home, 'Library/Application Support/CodexRingside'),
@@ -59,6 +60,19 @@ function agentConfig({ node, installDir = paths.installDir, logDir = paths.logDi
   };
 }
 
+// An independent, one-shot job survives bootout of the agent it is upgrading.
+function updateConfig({ node, installDir = paths.installDir, logDir = paths.logDir }) {
+  return {
+    Label: UPDATE_LABEL,
+    ProgramArguments: [node, path.join(installDir, 'src/update.cjs'), '--auto'],
+    RunAtLoad: true,
+    ProcessType: 'Background',
+    EnvironmentVariables: { NODE_OPTIONS: '', NODE_PATH: '' },
+    StandardOutPath: path.join(logDir, 'update.log'),
+    StandardErrorPath: path.join(logDir, 'update.err.log')
+  };
+}
+
 const launchctl = (...args) => execFileSync('/bin/launchctl', args, {
   encoding: 'utf8', timeout: 15000, stdio: ['ignore', 'pipe', 'pipe']
 });
@@ -88,4 +102,4 @@ function writePlist(config, file = paths.plist) {
   execFileSync('/usr/bin/plutil', ['-lint', file], { stdio: 'ignore' });
 }
 
-module.exports = { LABEL, LEGACY_LABEL, legacyPaths, agentConfig, bootout, bootstrap, paths, plistXml, printJob, trashItems, writePlist };
+module.exports = { LABEL, UPDATE_LABEL, LEGACY_LABEL, legacyPaths, agentConfig, updateConfig, bootout, bootstrap, paths, plistXml, printJob, trashItems, writePlist };

package/src/standalone.cjs

@@ -0,0 +1,30 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+// A manifest is only shipped in a release bundle, never in the npm source package.
+function inspectBundle(root) {
+  const file = path.join(root, 'standalone.json');
+  if (!fs.existsSync(file)) return null;
+  const info = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (info.format !== 1 || info.platform !== process.platform || info.arch !== process.arch
+    || info.version !== JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version) {
+    throw new Error('一键安装包的平台、架构或版本不匹配，请重新下载');
+  }
+  const node = path.join(root, 'runtime/node');
+  const version = execFileSync(node, ['--version'], { encoding: 'utf8', timeout: 10000 }).trim();
+  if (version !== `v${info.nodeVersion}` || Number(info.nodeVersion.split('.')[0]) < 22) throw new Error('安装包内 Node 版本不匹配');
+  // A side-effect-free command confirms the helper can load on this macOS version.
+  const helper = JSON.parse(execFileSync(path.join(root, 'bridge'), ['version'], { encoding: 'utf8', timeout: 10000 }));
+  if (helper.protocol !== 1) throw new Error('安装包内 helper 版本不匹配');
+  return info;
+}
+
+function copyBundle(root, stage) {
+  fs.cpSync(path.join(root, 'runtime'), path.join(stage, 'runtime'), { recursive: true });
+  for (const name of ['bridge', 'standalone.json']) fs.copyFileSync(path.join(root, name), path.join(stage, name));
+  fs.chmodSync(path.join(stage, 'bridge'), 0o755);
+}
+
+module.exports = { inspectBundle, copyBundle };

package/src/update.cjs

@@ -0,0 +1,271 @@
+'use strict';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+const launchd = require('./launchd.cjs');
+const installer = require('./install.cjs');
+const { inspectBundle } = require('./standalone.cjs');
+
+const run = promisify(execFile);
+const REPOSITORY = 'tccpc/codex-ringside';
+const RELEASE_API = `https://api.github.com/repos/${REPOSITORY}/releases/latest`;
+const CHECK_MS = 6 * 60 * 60 * 1000;
+const RETRY_MS = 60 * 60 * 1000;
+const SCAN_MS = 60000;
+const STATE_FILE = 'update-state.json';
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+function writeJson(file, value) {
+  const temp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temp, file);
+  } finally { fs.rmSync(temp, { force: true }); }
+}
+
+function readState(root) {
+  try { return readJson(path.join(root, STATE_FILE)) ?? {}; }
+  catch { return {}; } // A damaged diagnostic file must not disable updates forever.
+}
+
+function installation(root) {
+  const file = path.join(root, 'settings.json');
+  const settings = readJson(file);
+  const pkg = readJson(path.join(root, 'package.json'));
+  if (!settings || pkg?.name !== 'codex-ringside') throw Error('尚未安装，请先运行 install');
+  const stat = fs.statSync(file);
+  return { settings, version: pkg.version, stamp: `${stat.dev}:${stat.ino}:${stat.mtimeMs}:${stat.ctimeMs}` };
+}
+
+function versionParts(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+  if (!match) throw Error(`无效的版本号：${value}`);
+  return { numbers: match.slice(1, 4).map(BigInt), prerelease: !!match[4] };
+}
+
+// The remote channel only accepts stable versions; a matching stable beats its RC.
+function isNewer(latest, current) {
+  const a = versionParts(latest);
+  const b = versionParts(current);
+  if (a.prerelease) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a.numbers[i] !== b.numbers[i]) return a.numbers[i] > b.numbers[i];
+  }
+  return b.prerelease;
+}
+
+async function curl(url, destination, signal) {
+  const args = ['--fail', '--location', '--silent', '--show-error', '--retry', '2',
+    '--connect-timeout', '20', '--max-time', destination ? '600' : '30',
+    '--max-filesize', String(destination ? 256 * 1024 * 1024 : 1024 * 1024),
+    '--proto', '=https', '--proto-redir', '=https', '--user-agent', 'codex-ringside-updater'];
+  if (destination) args.push('--output', destination);
+  else args.push('--header', 'Accept: application/vnd.github+json');
+  args.push(url);
+  try {
+    const { stdout } = await run('/usr/bin/curl', args, {
+      encoding: 'utf8', timeout: destination ? 1900000 : 120000, maxBuffer: 1024 * 1024, signal
+    });
+    return stdout;
+  } catch (error) {
+    throw Error(`更新下载失败，请检查网络或稍后重试（${error.code ?? 'timeout'}）`);
+  }
+}
+
+async function fetchRelease(signal) {
+  return JSON.parse(await curl(RELEASE_API, undefined, signal));
+}
+
+function releaseInfo(release, arch = process.arch) {
+  if (release?.draft || release?.prerelease) return null;
+  if (!/^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(release?.tag_name ?? '')) {
+    throw Error('远程发行版不是有效的正式版本');
+  }
+  if (!['arm64', 'x64'].includes(arch)) throw Error('不支持的芯片架构');
+  const version = release.tag_name.slice(1);
+  const asset = `codex-ringside-v${version}-darwin-${arch}.tar.gz`;
+  const base = `https://github.com/${REPOSITORY}/releases/download/v${version}`;
+  return { version, asset, base, assets: release.assets };
+}
+
+function checksum(manifest, asset) {
+  const matches = manifest.split(/\r?\n/).map(line => /^([a-fA-F0-9]{64})\s+\*?(.+)$/.exec(line))
+    .filter(match => match?.[2] === asset);
+  if (matches.length !== 1) throw Error('发行版缺少唯一的安装包 SHA-256 校验值');
+  return matches[0][1].toLowerCase();
+}
+
+async function digest(file) {
+  const hash = crypto.createHash('sha256');
+  for await (const bytes of fs.createReadStream(file)) hash.update(bytes);
+  return hash.digest('hex');
+}
+
+async function extractBundle(archive, work, signal) {
+  const options = { encoding: 'utf8', timeout: 60000, maxBuffer: 4 * 1024 * 1024, signal };
+  const { stdout: names } = await run('/usr/bin/tar', ['-tzf', archive], options);
+  const { stdout: entries } = await run('/usr/bin/tar', ['-tvzf', archive], options);
+  const safePath = name => name.startsWith('codex-ringside/')
+    && !name.includes('\\') && !name.split('/').some(part => part === '..' || part === '.');
+  if (!names.trim() || !names.trimEnd().split('\n').every(safePath)
+    || !entries.trimEnd().split('\n').every(line => /^[-d]/.test(line))) {
+    throw Error('安装包包含不安全的路径或链接');
+  }
+  await run('/usr/bin/tar', ['-xzf', archive, '--no-same-owner', '--no-same-permissions', '-C', work], options);
+  return path.join(work, 'codex-ringside');
+}
+
+async function prepareBundle(release, work, { download = curl, inspect = inspectBundle, signal } = {}) {
+  for (const name of [release.asset, 'SHA256SUMS.txt']) {
+    if (!release.assets?.some(asset => asset.name === name && asset.state === 'uploaded')) {
+      throw Error(`发行版缺少安装文件：${name}`);
+    }
+  }
+  const sums = path.join(work, 'SHA256SUMS.txt');
+  const archive = path.join(work, release.asset);
+  await download(`${release.base}/SHA256SUMS.txt`, sums, signal);
+  const expected = checksum(fs.readFileSync(sums, 'utf8'), release.asset);
+  await download(`${release.base}/${release.asset}`, archive, signal);
+  if (await digest(archive) !== expected) throw Error('安装包 SHA-256 校验失败，未更改现有安装');
+  const payload = await extractBundle(archive, work, signal);
+  const pkg = readJson(path.join(payload, 'package.json'));
+  if (pkg?.name !== 'codex-ringside' || pkg.version !== release.version) throw Error('安装包版本不匹配');
+  const bundle = inspect(payload);
+  if (!bundle || bundle.version !== release.version) throw Error('安装包缺少有效的独立运行时');
+  return payload;
+}
+
+function updateStatus(root = launchd.paths.installDir) {
+  const installed = installation(root);
+  return { ...readState(root), enabled: installed.settings.autoUpdate !== false,
+    currentVersion: installed.version, source: RELEASE_API, checkIntervalHours: 6 };
+}
+
+async function setAutoUpdate(enabled, root = launchd.paths.installDir) {
+  await installer.withLock({ installDir: root }, async () => {
+    const { settings } = installation(root);
+    writeJson(path.join(root, 'settings.json'), { ...settings, autoUpdate: enabled });
+    if (enabled) writeJson(path.join(root, STATE_FILE), { ...readState(root), nextCheckAt: 0 });
+  });
+}
+
+async function runUpdate({ root = launchd.paths.installDir, automatic = false, checkOnly = false,
+  getRelease = fetchRelease, prepare = prepareBundle, install = installer.install, now = Date.now, signal } = {}) {
+  // A separate lock keeps manual checks and automatic downloads from running together.
+  return installer.withLock({ installDir: `${root}.update` }, async () => {
+    const initial = installation(root);
+    const beforeInstall = () => {
+      signal?.throwIfAborted();
+      const current = installation(root);
+      if (current.stamp !== initial.stamp || current.version !== initial.version
+        || (automatic && current.settings.autoUpdate === false)) {
+        throw Error('安装或更新设置已变化，取消本次更新');
+      }
+    };
+    const saved = readState(root);
+    if (automatic && (initial.settings.autoUpdate === false || (!isDue(saved, now()) && saved.status !== 'scheduled'))) {
+      return { status: 'skipped', currentVersion: initial.version };
+    }
+    let state = { ...readState(root), status: 'checking', lastAttemptAt: now(),
+      nextCheckAt: now() + RETRY_MS, error: null, attemptId: crypto.randomUUID() };
+    const save = patch => {
+      state = { ...state, ...patch };
+      // Never recreate an uninstalled root.
+      if (fs.existsSync(path.join(root, 'settings.json'))) writeJson(path.join(root, STATE_FILE), state);
+    };
+    save({});
+    let work;
+    try {
+      const release = releaseInfo(await getRelease(signal));
+      beforeInstall();
+      save({ lastCheckedAt: now(), latestVersion: release?.version ?? null });
+      if (!release || !isNewer(release.version, initial.version)) {
+        save({ status: 'up-to-date', nextCheckAt: now() + CHECK_MS });
+      } else if (checkOnly) {
+        save({ status: 'available', nextCheckAt: now() });
+      } else {
+        save({ status: 'downloading' });
+        work = fs.mkdtempSync(path.join(os.tmpdir(), 'ringside-update-'));
+        const payload = await prepare(release, work, { signal });
+        beforeInstall();
+        save({ status: 'installing' });
+        const result = await install({ repoRoot: payload, env: {}, beforeInstall });
+        save({ status: 'updated', installedVersion: release.version, updatedAt: now(),
+          backup: result.backup, nextCheckAt: now() + CHECK_MS });
+      }
+      return state;
+    } catch (error) {
+      if (readState(root).attemptId === state.attemptId) {
+        save({ status: 'failed', error: error.message, nextCheckAt: now() + RETRY_MS });
+      }
+      throw error;
+    } finally {
+      if (work) fs.rmSync(work, { recursive: true, force: true });
+    }
+  });
+}
+
+function isDue(state, now = Date.now()) {
+  // Clamp future timestamps so a clock correction cannot suppress updates indefinitely.
+  return !Number.isFinite(state.nextCheckAt) || state.nextCheckAt <= now || state.nextCheckAt > now + CHECK_MS;
+}
+
+async function scheduleUpdate({ root = launchd.paths.installDir, node = process.execPath,
+  logDir = launchd.paths.logDir, services = launchd, now = Date.now } = {}) {
+  const current = installation(root);
+  if (current.settings.autoUpdate === false || !isDue(readState(root), now())) return false;
+  return installer.withLock({ installDir: root }, async () => {
+    if (installation(root).settings.autoUpdate === false || !isDue(readState(root), now())) return false;
+    // Do not bootout a worker that is still downloading or completing a rollback.
+    if (/\bpid = \d+/.test(services.printJob(launchd.UPDATE_LABEL) ?? '')) return false;
+    await services.bootout(launchd.UPDATE_LABEL);
+    const file = path.join(root, `${launchd.UPDATE_LABEL}.plist`);
+    const state = { ...readState(root), status: 'scheduled', nextCheckAt: now() + RETRY_MS, error: null };
+    writeJson(path.join(root, STATE_FILE), state);
+    try {
+      services.writePlist(launchd.updateConfig({ node, installDir: root, logDir }), file);
+      services.bootstrap(file);
+    } catch (error) {
+      writeJson(path.join(root, STATE_FILE), { ...state, status: 'failed', error: error.message });
+      throw error;
+    }
+    return true;
+  });
+}
+
+function startAutoUpdater({ root, signal, log }) {
+  let running = false;
+  const tick = async () => {
+    if (running || signal.aborted) return;
+    running = true;
+    try { await scheduleUpdate({ root }); }
+    catch (error) { log(`update: ${error.message}`); }
+    finally { running = false; }
+  };
+  // Let installation finish its readiness check before launching the first update job.
+  const timer = setInterval(tick, SCAN_MS);
+  signal.addEventListener('abort', () => clearInterval(timer), { once: true });
+}
+
+module.exports = { CHECK_MS, RETRY_MS, RELEASE_API, isNewer, isDue, checksum, releaseInfo,
+  extractBundle, prepareBundle, runUpdate, updateStatus, setAutoUpdate, scheduleUpdate, startAutoUpdater };
+
+if (require.main === module) {
+  const abort = new AbortController();
+  const stop = () => abort.abort(Error('更新已取消'));
+  process.once('SIGTERM', stop);
+  process.once('SIGINT', stop);
+  runUpdate({ automatic: process.argv.includes('--auto'), signal: abort.signal }).then(result => {
+    console.log(`[${new Date().toISOString()}] update: ${result.status}`);
+  }).catch(error => {
+    console.error(`[${new Date().toISOString()}] update: ${error.message}`);
+    process.exitCode = 1;
+  });
+}