fix: skip redundant upgrades

Author: javazys

AGENTS.md

@@ -58,7 +58,7 @@ bun run dev -- db check  # 检查数据库完整性与业务统计
 - PM2 替换已有 Gateway 前必须先用保存的运行环境验证管理命令可执行，并用目标 Gateway 环境真实执行 `opencode --version`；若 OpenCode 不可执行，或新旧进程无法共用同一可回滚的 PM2 管理路径，必须在删除旧进程前失败关闭。
 - PM2 替换、数据库维护、卸载与 macOS supervisor 检查必须先共用 `PM2_HOME/supertask-gateway.manage.sqlite` canonical SQLite 事务锁；兼容旧 custom lock 时还必须从 PM2 dump/运行环境和 LaunchAgent 恢复全部旧路径，并按固定顺序同时持有，不能因后续 CLI 缺少旧环境变量而绕过旧 supervisor。已安装 LaunchAgent 的 `PM2_HOME` 与当前 CLI 不同必须在任何修改前失败关闭，避免两个 PM2 daemon 争用同一 Gateway。不得恢复 PID/stale 文件锁。PM2 kill timeout 不得低于 Worker shutdown grace 加 15 秒，`stop/delete` 命令 timeout 不得低于实际 kill timeout 加 5 秒，管理锁必须持有到命令返回；显式低值必须在删除旧进程前失败关闭。
 - macOS supervisor 只有在 `jlist` 成功且确认 Gateway 缺失、同时 `dump.pm2` 明确包含 Gateway 时才可 `resurrect`；状态未知、`errored`、`stopped` 和卸载后的空 dump 都不得触发重启。卸载必须停止并移除项目 LaunchAgent。
-- `/health` 必须分别反映 Worker、Scheduler、Watchdog 和历史清理的活跃度与连续失败；`supertask doctor` 要分别验证当前终端和 PM2 保存的 Gateway 环境中的 OpenCode，再解析最终配置，要求唯一的精确插件版本，核对对应缓存、全局 CLI、PM2 实际 Gateway 入口包和 ready 锁版本，并验证 macOS LaunchAgent 与 PM2 dump 可恢复性。`doctor --smoke` 必须经真实数据库队列和 Gateway 执行 OpenCode、验证输出标记，普通 `doctor` 不得调用模型。浮动 `@latest`/`@next` 入口或任一组件版本不一致必须失败。升级成功替换插件和 Gateway 后必须检测全局 CLI 的 npm/Bun 安装来源并同步精确版本；无法确认时返回明确的部分失败和人工命令。PM2 自动替换/恢复必须保留既有 Bun 路径、完整运行环境和数据库作用域。用户显式执行 `install` / `upgrade` 时，目标 Gateway 可从当前终端刷新 OpenCode、XDG 与 Provider 执行环境，但必须固定旧 `HOME`、`PATH`、`PM2_HOME`、全部 `SUPERTASK_*`、Bun 路径、cwd 和数据库/配置作用域；失败回滚必须使用未修改的完整旧环境。
+- `/health` 必须分别反映 Worker、Scheduler、Watchdog 和历史清理的活跃度与连续失败；`supertask doctor` 要分别验证当前终端和 PM2 保存的 Gateway 环境中的 OpenCode，再解析最终配置，要求唯一的精确插件版本，核对对应缓存、全局 CLI、PM2 实际 Gateway 入口包和 ready 锁版本，并验证 macOS LaunchAgent 与 PM2 dump 可恢复性。`doctor --smoke` 必须经真实数据库队列和 Gateway 执行 OpenCode、验证输出标记，普通 `doctor` 不得调用模型。浮动 `@latest`/`@next` 入口或任一组件版本不一致必须失败。`supertask upgrade` 在当前包、有效插件、缓存、CLI 和就绪 Gateway 已全部匹配 npm `latest` 时必须无副作用返回；`upgrade --force` 才允许在同版本下重新安装并重启。升级成功替换插件和 Gateway 后必须检测全局 CLI 的 npm/Bun 安装来源并同步精确版本；无法确认时返回明确的部分失败和人工命令。PM2 自动替换/恢复必须保留既有 Bun 路径、完整运行环境和数据库作用域。用户显式执行 `install`、版本变化的 `upgrade` 或 `upgrade --force` 时，目标 Gateway 可从当前终端刷新 OpenCode、XDG 与 Provider 执行环境，但必须固定旧 `HOME`、`PATH`、`PM2_HOME`、全部 `SUPERTASK_*`、Bun 路径、cwd 和数据库/配置作用域；失败回滚必须使用未修改的完整旧环境。
 - 数据库检查、备份、清空和恢复统一经过 `DatabaseMaintenanceService`；CLI 清空/恢复必须显式确认并拒绝运行中任务，且只可自动停启 PID 与当前数据库新鲜 ready 锁一致的 PM2 Gateway；前台或无法确认归属的进程必须拒绝误杀。清空/恢复前必须自动创建校验通过的安全备份；清空必须动态删除全部业务表数据（包括 N+1 expand-only 表），通过延迟外键检查支持循环依赖，并保留 `gateway_lock` 与 migration 元数据。恢复来源必须从已打开的 SQLite 连接生成包含已提交 WAL 页的一致快照，并拒绝当前数据库的符号链接/硬链接别名。恢复必须动态校验 source/live 业务表和可写列：source-only 未知表/列在删除前失败关闭，共有未来列完整复制，live-only 列只允许可空/默认值且 live-only 新表必须清空，避免 N/N-1 形成混合时间点；随后在当前连接的排他事务内原位替换，不得关闭连接后 rename 换库。默认在操作失败时也恢复原 Gateway 状态，`--keep-stopped` 除外。
 - Dashboard 清空只能豁免当前 Gateway PID，仍必须服务端确认、拒绝运行中任务并在同一事务内先备份后动态删除全部业务表；不得恢复为路由内直接 `DELETE` 的实现。
 - Dashboard 的浏览器写请求必须通过同源检查，数据库字符串进入 HTML 前必须调用 `esc`；API 的 ID、状态和配置不得直接断言类型。

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable user-facing changes are recorded here. This project follows semantic versioning while it is in the `0.x` development series.
 
+## [0.1.39] - 2026-07-18
+
+### Fixed
+
+- `supertask upgrade` now exits without reinstalling or restarting when the CLI, effective plugin configuration, plugin cache, and ready PM2 Gateway already match npm `latest`.
+- Added `supertask upgrade --force` for intentionally reinstalling the current version, refreshing the Gateway environment, and restarting PM2.
+- The OpenCode `supertask_upgrade` tool now reports an up-to-date no-op instead of restarting an already converged Gateway.
+
+[0.1.39]: https://github.com/vbgate/opencode-supertask/compare/v0.1.38...v0.1.39
+
 ## [0.1.38] - 2026-07-18
 
 ### Fixed

README.md

@@ -32,11 +32,11 @@ supertask gateway   # foreground mode: no pm2 required
 
 The plugin never installs global dependencies by itself. Without a running Gateway, queue-management tools still work, but scheduled and queued tasks are not executed and the Dashboard is unavailable.
 
-Upgrades do not require uninstalling. Run `supertask upgrade`: it pins the exact latest plugin, replaces the Gateway, detects whether the global `supertask` came from npm or Bun, and synchronizes the CLI to that same version. `supertask doctor` fails if the CLI, plugin, Gateway package, or ready lock disagree. Versions through 0.1.33 cannot retroactively update their own old CLI, so upgrade from those releases by installing the new global CLI once with the original package manager, then run the new `supertask upgrade`.
+Upgrades do not require uninstalling. Run `supertask upgrade`: it pins the exact latest plugin, replaces the Gateway, detects whether the global `supertask` came from npm or Bun, and synchronizes the CLI to that same version. When the CLI, effective plugin, cache, and ready Gateway already match npm `latest`, the command exits without reinstalling or restarting; use `supertask upgrade --force` to intentionally refresh the environment and restart the current version. `supertask doctor` fails if the CLI, plugin, Gateway package, or ready lock disagree. Versions through 0.1.33 cannot retroactively update their own old CLI, so upgrade from those releases by installing the new global CLI once with the original package manager, then run the new `supertask upgrade`.
 
 Gateway task execution currently requires macOS or Linux. Windows is rejected at startup until the Worker can use an OS Job Object to guarantee that detached OpenCode descendants cannot survive cancellation or recovery.
 
-Run `supertask install` and `supertask upgrade` from the same terminal environment in which `opencode run --agent <name>` works. An explicit install or upgrade refreshes the Gateway's OpenCode/XDG/provider execution environment while keeping the proven Bun path, PM2 identity, database/config scope, and rollback runtime pinned. This matters when a custom primary agent selects a provider through environment variables or a non-default OpenCode config directory.
+Run `supertask install` and `supertask upgrade` from the same terminal environment in which `opencode run --agent <name>` works. An install or version-changing upgrade refreshes the Gateway's OpenCode/XDG/provider execution environment while keeping the proven Bun path, PM2 identity, database/config scope, and rollback runtime pinned. Use `supertask upgrade --force` when the version is already current but the saved environment needs refreshing.
 
 ### Uninstall
 
@@ -131,7 +131,7 @@ supertask config                       # show current config
 supertask doctor [--json]              # static end-to-end runtime diagnostics
 supertask doctor --smoke [--smoke-agent build] [--smoke-model provider/model]
                                         # queue one real Gateway/OpenCode verification task
-supertask upgrade                      # pin latest plugin version and replace Gateway
+supertask upgrade [--force]            # update if needed; force refreshes and restarts
 
 # Task management
 supertask add -n "Task" -a "agent" -p "prompt" --importance 5 \
@@ -295,9 +295,9 @@ supertask gateway   # 前台运行：不需要 pm2
 
 插件不会自行安装全局依赖。Gateway 未运行时仍可管理队列，但不会执行排队/定时任务，也不会启动 Web 控制台。
 
-升级无需卸载，执行 `supertask upgrade`。它会精确安装最新插件、替换 Gateway，并根据全局 `supertask` 的真实路径识别 npm 或 Bun 后同步 CLI；无法安全确认包管理器时会明确失败并给出精确命令。`doctor` 把 CLI、插件、Gateway 任一版本不一致视为异常。由于 0.1.33 及更早版本还不具备 CLI 自动同步能力，从这些版本升级时先用原包管理器安装一次新 CLI，再运行新版 `supertask upgrade`。
+升级无需卸载，执行 `supertask upgrade`。它会精确安装最新插件、替换 Gateway，并根据全局 `supertask` 的真实路径识别 npm 或 Bun 后同步 CLI；当 CLI、有效插件配置、缓存和就绪 Gateway 已全部匹配 npm `latest` 时直接返回，不重新安装或重启。需要在同版本下强制刷新环境时执行 `supertask upgrade --force`。无法安全确认包管理器时会明确失败并给出精确命令。`doctor` 把 CLI、插件、Gateway 任一版本不一致视为异常。由于 0.1.33 及更早版本还不具备 CLI 自动同步能力，从这些版本升级时先用原包管理器安装一次新 CLI，再运行新版 `supertask upgrade`。
 
-请在手动执行 `opencode run --agent <名称>` 能工作的同一个终端环境中运行 `supertask install` 或 `supertask upgrade`。显式安装/升级会刷新 Gateway 使用的 OpenCode、XDG 与模型 Provider 执行环境，同时固定已经验证的 Bun、PM2、数据库/配置作用域，并保留完整旧环境用于失败回滚。这能避免自定义主 Agent 在终端正常、但 Gateway 仍沿用旧 Provider 凭据或旧 OpenCode 配置目录。
+请在手动执行 `opencode run --agent <名称>` 能工作的同一个终端环境中运行 `supertask install` 或 `supertask upgrade`。安装或发生版本变化的升级会刷新 Gateway 使用的 OpenCode、XDG 与模型 Provider 执行环境，同时固定已经验证的 Bun、PM2、数据库/配置作用域，并保留完整旧环境用于失败回滚。同版本下需要刷新旧 Provider 凭据或 OpenCode 配置目录时使用 `supertask upgrade --force`。
 
 ### 快速开始
 

docs/operations.md

@@ -48,11 +48,12 @@ Dashboard 会区分配置文件中的“已保存值”和当前 Gateway 的“
 
 ```bash
 supertask upgrade
+supertask upgrade --force  # 同版本下仍重新安装、刷新环境并重启
 ```
 
-升级先查询 npm 的 `latest` 精确版本，再用 `opencode plugin opencode-supertask@<version> --global --force` 写入精确配置并确认对应缓存真实存在，最后用该缓存包的 Gateway 入口替换 PM2 进程；新 Gateway 未 ready 会回滚旧入口和旧插件版本。陈旧 `@latest` 目录可以保留，因为不会被当作目标版本；`supertask doctor` 会检查实际选中的配置和入口。OpenCode 进程仍需重启才能加载新插件。
+升级先查询 npm 的 `latest` 精确版本。若当前 CLI、有效插件配置、插件缓存和就绪 PM2 Gateway 已全部匹配该版本，命令直接返回且不修改配置、不重启。否则用 `opencode plugin opencode-supertask@<version> --global --force` 写入精确配置并确认对应缓存真实存在，最后用该缓存包的 Gateway 入口替换 PM2 进程；新 Gateway 未 ready 会回滚旧入口和旧插件版本。陈旧 `@latest` 目录可以保留，因为不会被当作目标版本；`supertask doctor` 会检查实际选中的配置和入口。OpenCode 进程仍需重启才能加载新插件。
 
-显式 `install` / `upgrade` 还会从当前终端刷新 Gateway 的 OpenCode、XDG 与 Provider 执行环境；`HOME`、`PATH`、`PM2_HOME` 和全部 `SUPERTASK_*` 运行作用域继续使用已经验证的旧值，Bun 路径与 cwd 也不变。删除旧 Gateway 前，目标环境必须先真实执行 `opencode --version`；预检失败不会中断当前 Gateway。新 Gateway 未 ready 时，回滚使用未修改的完整旧环境。因此，自定义 Agent 只有在终端手动执行时正常的情况，应从该终端运行 `supertask install` 或 `supertask upgrade` 后再重试。PM2 环境与 dump 会持久化运行所需环境变量；敏感 Provider 凭据应按本机敏感文件同等级别保护 `PM2_HOME`。
+显式 `install`、发生版本变化的 `upgrade`，以及 `upgrade --force` 会从当前终端刷新 Gateway 的 OpenCode、XDG 与 Provider 执行环境；普通 `upgrade` 在全部组件已是最新时不会重启。`HOME`、`PATH`、`PM2_HOME` 和全部 `SUPERTASK_*` 运行作用域继续使用已经验证的旧值，Bun 路径与 cwd 也不变。删除旧 Gateway 前，目标环境必须先真实执行 `opencode --version`；预检失败不会中断当前 Gateway。新 Gateway 未 ready 时，回滚使用未修改的完整旧环境。因此，自定义 Agent 只有在终端手动执行时正常、且当前版本已经最新的情况下，应从该终端运行 `supertask upgrade --force` 后再重试。PM2 环境与 dump 会持久化运行所需环境变量；敏感 Provider 凭据应按本机敏感文件同等级别保护 `PM2_HOME`。
 
 新版升级命令会从全局 `supertask` 的真实路径识别 npm 或 Bun，并在插件和 Gateway 成功替换后同步相同精确版本的 CLI；若找不到全局 CLI 则跳过，若 CLI 存在但无法确认包管理器则返回部分失败并给出人工命令。0.1.33 及更早版本没有这项能力，从旧版本升级时必须先人工更新一次 CLI，再运行新版升级流程：
 
@@ -227,7 +228,7 @@ cd <任务 cwd>
 opencode run --agent <agent> --format json [-m <model>] '<prompt>'
 ```
 
-若完全相同的命令在终端成功、Gateway 仍以 `Unexpected server error` 或 Provider 认证错误退出，通常说明 PM2 保存的 OpenCode/XDG/Provider 环境已落后。在这个手动命令可工作的终端执行 `supertask install`；版本升级场景执行 `supertask upgrade`。两者都会刷新执行环境并安全替换 Gateway，无需先卸载。若仍失败，保留任务/run 的完整输出和 `pm2 logs supertask-gateway`，不要只用 `general` 验证：OpenCode 可能把非主 Agent 名称降级到默认 Agent。
+若完全相同的命令在终端成功、Gateway 仍以 `Unexpected server error` 或 Provider 认证错误退出，通常说明 PM2 保存的 OpenCode/XDG/Provider 环境已落后。在这个手动命令可工作的终端执行 `supertask install`；有新版本时执行 `supertask upgrade`，已经最新时执行 `supertask upgrade --force`。这些命令会刷新执行环境并安全替换 Gateway，无需先卸载。若仍失败，保留任务/run 的完整输出和 `pm2 logs supertask-gateway`，不要只用 `general` 验证：OpenCode 可能把非主 Agent 名称降级到默认 Agent。
 
 ### Gateway 提示已有实例
 
@@ -311,11 +312,12 @@ cp ~/.config/opencode/supertask.json ~/supertask-backup/supertask.json
 ## 升级与卸载
 
 ```bash
-supertask upgrade     # 刷新 OpenCode 插件缓存并重启 PM2 Gateway
+supertask upgrade             # 有版本或组件漂移时更新，否则不重启
+supertask upgrade --force     # 同版本强制刷新环境并重启
 supertask uninstall   # 仅从 PM2 移除 Gateway，保留其他 PM2 项和数据
 ```
 
-`upgrade` 先从 npm `dist-tags.latest` 查询具体版本，再让 OpenCode 安装该精确版本；只有缓存包版本完全一致且包含 `dist/gateway/index.js` 时才切换 PM2。替换和回滚都复用原 PM2 保存的 Bun 路径与完整环境，ready 检查也针对原数据库，避免升级后静默切换数据域。该命令要求 npm、OpenCode CLI 和 PM2 已安装。数据库迁移会在新版本首次初始化时自动运行；升级前备份是低成本的安全措施。
+`upgrade` 先从 npm `dist-tags.latest` 查询具体版本，并检查 CLI、有效插件、缓存、Gateway 入口包、ready 版本和运行作用域；全部一致时直接退出。需要更新时才让 OpenCode 安装精确版本并切换 PM2，`--force` 则跳过 no-op 短路。替换和回滚都复用原 PM2 保存的 Bun 路径与完整环境，ready 检查也针对原数据库，避免升级后静默切换数据域。该命令要求 npm、OpenCode CLI 和 PM2 已安装。数据库迁移会在新版本首次初始化时自动运行；升级前备份是低成本的安全措施。
 
 升级必须从 Gateway 外部发起。Worker 管理的队列任务会被标记为受管执行上下文，插件在其中拒绝 `supertask_upgrade`；不要把“升级 SuperTask”作为队列任务提交，否则升级会返回安全拒绝提示。
 

package.json

@@ -1,6 +1,6 @@
 {
     "name": "opencode-supertask",
-    "version": "0.1.38",
+    "version": "0.1.39",
     "description": "AI Agent 任务调度系统 — OpenCode 插件 + CLI + Gateway 常驻进程",
     "type": "module",
     "main": "dist/plugin/supertask.js",