openclaw - 💡(How to fix) Fix \`openclaw update\` dry-run passes but apply fails with `ETARGET` when version not yet on npm registry

Summary

openclaw update --tag <version> --dry-run reports the update is safe and ready to apply when a fresh stable version exists on GitHub releases but has not yet propagated to the npm registry. The subsequent apply (without --dry-run) then fails with npm ETARGET. This is a confusing UX gap during the npm propagation window after a release.

Reproduction (production observation)

OpenClaw stable v2026.5.26 published to GitHub at 2026-05-27T11:27:24Z (commit 10ad3aa).

At ~12:14Z (~47 min later), npm registry had not yet propagated:

$ npm view [email protected] version
npm error code E404
npm error 404 No match found for version 2026.5.26

npm view openclaw dist-tags showed latest=2026.5.22, beta=2026.5.26-beta.2 — no 2026.5.26 stable on npm yet.

openclaw update --channel stable --tag 2026.5.26 --dry-run --json during this window resolved cleanly:

• targetVersion: "2026.5.26"
• current: "2026.5.24-beta.2"
• downgradeRisk: false
• No warnings, output indicated the update path was clean

Running the apply (--channel stable --tag 2026.5.26 --yes --no-restart --json — same flags, no --dry-run) failed before mutation:

npm error code ETARGET
npm error notarget No matching version found for [email protected].

Installed bytes remained at 2026.5.24-beta.2, no restart happened, safe-fail behavior was correct. But the dry-run had given a green light.

The version was eventually propagated to npm at 13:21Z (1h54m after GitHub release). The same --channel stable --tag 2026.5.26 apply then succeeded cleanly, landing 2026.5.26 (commit 10ad3aa), gateway restarted, validator clean, all post-update gates passed.

Expected behavior

Dry-run should fail at the same gate apply fails, or at minimum surface a warning when the target version is not yet present on the npm registry's latest dist-tag, so the user knows the apply will fail until propagation completes.

Suggested options

1. Dry-run probes npm latest dist-tag for the target version — fail closed if not yet present (or warn explicitly that "registry has not yet propagated this version; apply will fail until npm publishes")
2. Document the propagation-lag scenario in the Update docs so users running update --tag <new-stable> within ~2h of a GitHub release know to wait
3. Have apply automatically fall back to the GitHub package-spec install path when npm ETARGET fires for the requested --tag, since --tag already supports GitHub specs per update.md docs and the source-of-truth GitHub release is unambiguous

Impact

• Time wasted: ~15-25 min on the failed apply + diagnostic before realizing it was a propagation timing issue
• User confusion: dry-run green light → apply red, contradictory signals from the same tool with the same flags
• Workaround in docs (--tag github:openclaw/openclaw#v2026.5.26) is technically accepted but flags targetVersion=null in dry-run output, losing the standard version-resolution preview

Environment

• OpenClaw 2026.5.24-beta.2 upgrading to 2026.5.26 (stable channel)
• Linux Ubuntu VPS, global npm install via ~/.npm-global
• No data loss, no rollback, update eventually succeeded after npm propagation

Filed as UX improvement for future stable releases.