fix: keep beta on newer prereleases

.agents/skills/openclaw-release-maintainer/SKILL.md

@@ -17,7 +17,7 @@ Use this skill for release and publish-time workflow. Keep ordinary development
 
 ## Keep release channel naming aligned
 
-- `stable`: tagged releases only, with npm dist-tag `latest`
+- `stable`: tagged releases only, published to npm `latest` and then mirrored onto npm `beta` unless `beta` already points at a newer prerelease
 - `beta`: prerelease tags like `vYYYY.M.D-beta.N`, with npm dist-tag `beta`
 - Prefer `-beta.N`; do not mint new `-1` or `-2` beta suffixes
 - `dev`: moving head on `main`

docs/reference/RELEASING.md

@@ -10,7 +10,7 @@ read_when:
 
 OpenClaw has three public release lanes:
 
-- stable: tagged releases that publish to npm `latest`
+- stable: tagged releases that publish to npm `latest` and mirror the same version onto `beta` unless `beta` already points at a newer prerelease
 - beta: prerelease tags that publish to npm `beta`
 - dev: the moving head of `main`
 
@@ -24,8 +24,8 @@ OpenClaw has three public release lanes:
   - Git tag: `vYYYY.M.D-beta.N`
 - Do not zero-pad month or day
 - `latest` means the current stable npm release
-- `beta` means the current prerelease npm release
-- Stable correction releases also publish to npm `latest`
+- `beta` means the current beta install target, which may point to either the active prerelease or the latest promoted stable build
+- Stable and stable correction releases publish to npm `latest` and also retag npm `beta` to that same non-beta version after promotion, unless `beta` already points at a newer prerelease
 - Every OpenClaw release ships the npm package and macOS app together
 
 ## Release cadence

scripts/lib/plugin-npm-release.ts

@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process";
 import { mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { parseReleaseVersion } from "../openclaw-npm-release-check.ts";
+import { parseReleaseVersion, resolveNpmPublishPlan } from "../openclaw-npm-release-check.ts";
 
 export type PluginPackageJson = {
   name?: string;
@@ -235,7 +235,7 @@ export function collectPublishablePluginPackages(
       packageName: packageJson.name!.trim(),
       version,
       channel: parsedVersion.channel,
-      publishTag: parsedVersion.channel === "beta" ? "beta" : "latest",
+      publishTag: resolveNpmPublishPlan(version).publishTag,
       installNpmSpec: packageJson.openclaw?.install?.npmSpec?.trim() || undefined,
     });
   }

scripts/openclaw-npm-publish.sh

@@ -10,18 +10,31 @@ if [[ "${mode}" != "--publish" ]]; then
 fi
 
 package_version="$(node -p "require('./package.json').version")"
-publish_cmd=(npm publish --access public --provenance)
-release_channel="stable"
+current_beta_version="$(npm view openclaw dist-tags.beta 2>/dev/null || true)"
+mapfile -t publish_plan < <(
+  PACKAGE_VERSION="${package_version}" CURRENT_BETA_VERSION="${current_beta_version}" node --import tsx --input-type=module <<'EOF'
+import { resolveNpmPublishPlan } from "./scripts/openclaw-npm-release-check.ts";
 
-if [[ "${package_version}" == *-beta.* ]]; then
-  publish_cmd=(npm publish --access public --tag beta --provenance)
-  release_channel="beta"
-elif [[ "${package_version}" == *-* ]]; then
-  publish_cmd=(npm publish --access public --tag latest --provenance)
-fi
+const plan = resolveNpmPublishPlan(
+  process.env.PACKAGE_VERSION ?? "",
+  process.env.CURRENT_BETA_VERSION,
+);
+console.log(plan.channel);
+console.log(plan.publishTag);
+console.log(plan.mirrorDistTags.join(","));
+EOF
+)
+
+release_channel="${publish_plan[0]}"
+publish_tag="${publish_plan[1]}"
+mirror_dist_tags_csv="${publish_plan[2]:-}"
+publish_cmd=(npm publish --access public --tag "${publish_tag}" --provenance)
 
 echo "Resolved package version: ${package_version}"
+echo "Current beta dist-tag: ${current_beta_version:-<missing>}"
 echo "Resolved release channel: ${release_channel}"
+echo "Resolved publish tag: ${publish_tag}"
+echo "Resolved mirror dist-tags: ${mirror_dist_tags_csv:-<none>}"
 echo "Publish auth: GitHub OIDC trusted publishing"
 
 printf 'Publish command:'
@@ -29,3 +42,12 @@ printf ' %q' "${publish_cmd[@]}"
 printf '\n'
 
 "${publish_cmd[@]}"
+
+if [[ -n "${mirror_dist_tags_csv}" ]]; then
+  IFS=',' read -r -a mirror_dist_tags <<< "${mirror_dist_tags_csv}"
+  for dist_tag in "${mirror_dist_tags[@]}"; do
+    [[ -n "${dist_tag}" ]] || continue
+    echo "Mirroring openclaw@${package_version} onto dist-tag ${dist_tag}"
+    npm dist-tag add "openclaw@${package_version}" "${dist_tag}"
+  done
+fi

scripts/openclaw-npm-release-check.ts

@@ -37,6 +37,12 @@ export type ParsedReleaseTag = {
   date: Date;
 };
 
+export type NpmPublishPlan = {
+  channel: "stable" | "beta";
+  publishTag: "latest" | "beta";
+  mirrorDistTags: ("latest" | "beta")[];
+};
+
 const STABLE_VERSION_REGEX = /^(?<year>\d{4})\.(?<month>[1-9]\d?)\.(?<day>[1-9]\d?)$/;
 const BETA_VERSION_REGEX =
   /^(?<year>\d{4})\.(?<month>[1-9]\d?)\.(?<day>[1-9]\d?)-beta\.(?<beta>[1-9]\d*)$/;
@@ -139,6 +145,68 @@ export function parseReleaseVersion(version: string): ParsedReleaseVersion | nul
   return null;
 }
 
+export function compareReleaseVersions(left: string, right: string): number | null {
+  const parsedLeft = parseReleaseVersion(left);
+  const parsedRight = parseReleaseVersion(right);
+  if (parsedLeft === null || parsedRight === null) {
+    return null;
+  }
+
+  const dateDelta = parsedLeft.date.getTime() - parsedRight.date.getTime();
+  if (dateDelta !== 0) {
+    return Math.sign(dateDelta);
+  }
+
+  if (parsedLeft.channel !== parsedRight.channel) {
+    return parsedLeft.channel === "stable" ? 1 : -1;
+  }
+
+  if (parsedLeft.channel === "beta" && parsedRight.channel === "beta") {
+    return Math.sign((parsedLeft.betaNumber ?? 0) - (parsedRight.betaNumber ?? 0));
+  }
+
+  return Math.sign((parsedLeft.correctionNumber ?? 0) - (parsedRight.correctionNumber ?? 0));
+}
+
+export function resolveNpmPublishPlan(
+  version: string,
+  currentBetaVersion?: string | null,
+): NpmPublishPlan {
+  const parsedVersion = parseReleaseVersion(version);
+  if (parsedVersion === null) {
+    throw new Error(`Unsupported release version "${version}".`);
+  }
+
+  if (parsedVersion.channel === "beta") {
+    return {
+      channel: "beta",
+      publishTag: "beta",
+      mirrorDistTags: [],
+    };
+  }
+
+  const normalizedCurrentBeta = currentBetaVersion?.trim();
+  if (normalizedCurrentBeta) {
+    const betaVsStable = compareReleaseVersions(normalizedCurrentBeta, version);
+    if (betaVsStable !== null && betaVsStable > 0) {
+      return {
+        channel: "stable",
+        publishTag: "latest",
+        // Keep beta on the newer prerelease train when one already exists.
+        mirrorDistTags: [],
+      };
+    }
+  }
+
+  return {
+    channel: "stable",
+    publishTag: "latest",
+    // Stable promotion keeps beta aligned unless beta already points at a
+    // newer prerelease train.
+    mirrorDistTags: ["beta"],
+  };
+}
+
 export function parseReleaseTagVersion(version: string): ParsedReleaseTag | null {
   const trimmed = version.trim();
   if (!trimmed) {

scripts/plugin-npm-publish.sh

@@ -17,20 +17,33 @@ fi
 
 package_name="$(node -e 'const pkg = require(require("node:path").resolve(process.argv[1], "package.json")); console.log(pkg.name)' "${package_dir}")"
 package_version="$(node -e 'const pkg = require(require("node:path").resolve(process.argv[1], "package.json")); console.log(pkg.version)' "${package_dir}")"
-publish_cmd=(npm publish --access public --provenance)
-release_channel="stable"
+current_beta_version="$(npm view "${package_name}" dist-tags.beta 2>/dev/null || true)"
+mapfile -t publish_plan < <(
+  PACKAGE_VERSION="${package_version}" CURRENT_BETA_VERSION="${current_beta_version}" node --import tsx --input-type=module <<'EOF'
+import { resolveNpmPublishPlan } from "./scripts/openclaw-npm-release-check.ts";
 
-if [[ "${package_version}" == *-beta.* ]]; then
-  publish_cmd=(npm publish --access public --tag beta --provenance)
-  release_channel="beta"
-elif [[ "${package_version}" == *-* ]]; then
-  publish_cmd=(npm publish --access public --tag latest --provenance)
-fi
+const plan = resolveNpmPublishPlan(
+  process.env.PACKAGE_VERSION ?? "",
+  process.env.CURRENT_BETA_VERSION,
+);
+console.log(plan.channel);
+console.log(plan.publishTag);
+console.log(plan.mirrorDistTags.join(","));
+EOF
+)
+
+release_channel="${publish_plan[0]}"
+publish_tag="${publish_plan[1]}"
+mirror_dist_tags_csv="${publish_plan[2]:-}"
+publish_cmd=(npm publish --access public --tag "${publish_tag}" --provenance)
 
 echo "Resolved package dir: ${package_dir}"
 echo "Resolved package name: ${package_name}"
 echo "Resolved package version: ${package_version}"
+echo "Current beta dist-tag: ${current_beta_version:-<missing>}"
 echo "Resolved release channel: ${release_channel}"
+echo "Resolved publish tag: ${publish_tag}"
+echo "Resolved mirror dist-tags: ${mirror_dist_tags_csv:-<none>}"
 echo "Publish auth: GitHub OIDC trusted publishing"
 
 printf 'Publish command:'
@@ -44,4 +57,13 @@ fi
 (
   cd "${package_dir}"
   "${publish_cmd[@]}"
+
+  if [[ -n "${mirror_dist_tags_csv}" ]]; then
+    IFS=',' read -r -a mirror_dist_tags <<< "${mirror_dist_tags_csv}"
+    for dist_tag in "${mirror_dist_tags[@]}"; do
+      [[ -n "${dist_tag}" ]] || continue
+      echo "Mirroring ${package_name}@${package_version} onto dist-tag ${dist_tag}"
+      npm dist-tag add "${package_name}@${package_version}" "${dist_tag}"
+    done
+  fi
 )

test/openclaw-npm-release-check.test.ts

@@ -1,11 +1,13 @@
 import { describe, expect, it } from "vitest";
 import {
+  compareReleaseVersions,
   collectControlUiPackErrors,
   collectReleasePackageMetadataErrors,
   collectReleaseTagErrors,
   parseNpmPackJsonOutput,
   parseReleaseTagVersion,
   parseReleaseVersion,
+  resolveNpmPublishPlan,
   resolveNpmCommandInvocation,
   utcCalendarDayDistance,
 } from "../scripts/openclaw-npm-release-check.ts";
@@ -72,6 +74,66 @@ describe("parseReleaseTagVersion", () => {
   });
 });
 
+describe("resolveNpmPublishPlan", () => {
+  it("publishes beta prereleases to beta only", () => {
+    expect(resolveNpmPublishPlan("2026.3.29-beta.2")).toEqual({
+      channel: "beta",
+      publishTag: "beta",
+      mirrorDistTags: [],
+    });
+  });
+
+  it("publishes stable releases to latest and mirrors beta", () => {
+    expect(resolveNpmPublishPlan("2026.3.29")).toEqual({
+      channel: "stable",
+      publishTag: "latest",
+      mirrorDistTags: ["beta"],
+    });
+  });
+
+  it("mirrors beta for stable correction releases too", () => {
+    expect(resolveNpmPublishPlan("2026.3.29-2")).toEqual({
+      channel: "stable",
+      publishTag: "latest",
+      mirrorDistTags: ["beta"],
+    });
+  });
+
+  it("does not mirror beta when beta already points at a newer prerelease", () => {
+    expect(resolveNpmPublishPlan("2026.3.29", "2026.3.30-beta.1")).toEqual({
+      channel: "stable",
+      publishTag: "latest",
+      mirrorDistTags: [],
+    });
+  });
+
+  it("still mirrors beta when beta points at the same release line", () => {
+    expect(resolveNpmPublishPlan("2026.3.29", "2026.3.29-beta.2")).toEqual({
+      channel: "stable",
+      publishTag: "latest",
+      mirrorDistTags: ["beta"],
+    });
+  });
+});
+
+describe("compareReleaseVersions", () => {
+  it("treats stable as newer than same-day beta", () => {
+    expect(compareReleaseVersions("2026.3.29", "2026.3.29-beta.2")).toBe(1);
+  });
+
+  it("treats a newer beta day as newer than an older stable day", () => {
+    expect(compareReleaseVersions("2026.3.30-beta.1", "2026.3.29")).toBe(1);
+  });
+
+  it("orders stable correction releases after the base stable release", () => {
+    expect(compareReleaseVersions("2026.3.29-2", "2026.3.29")).toBe(1);
+  });
+
+  it("returns null when either version is not release-shaped", () => {
+    expect(compareReleaseVersions("latest", "2026.3.29")).toBeNull();
+  });
+});
+
 describe("utcCalendarDayDistance", () => {
   it("compares UTC calendar days rather than wall-clock hours", () => {
     const left = new Date("2026-03-09T23:59:59Z");