release-openclaw-maintainer

name	release-openclaw-maintainer
description	Prepare or verify OpenClaw stable, beta, and extended-stable releases, including backport discovery, changelogs, release notes, publish commands, and artifacts.

OpenClaw Release Maintainer

Use this skill for release and publish-time workflow, including preparing the approved backport set for an extended-stable maintenance release. Load $release-private if it exists before resolving Peter-owned credential locators or private host topology. Keep ordinary development changes and GHSA-specific advisory work outside this skill.

Freeze the release state

Before validation or publication, write one compact state record and keep it current:

• goal and terminal success criteria
• release version, tag, branch, cut SHA, Code SHA, Tooling SHA, and Release SHA
• active Full Release Validation parent run id and attempt
• npm preflight and publish parent run ids
• completed phases and immutable child artifacts
• approved backports or main changes
• current phase, next action, and one precise blocker if stopped

Use references/release-handoff-template.md when starting a release session, recovering after compaction, or handing the release to another operator. After compaction, resume, or new steering, the latest explicit operator instruction replaces the effective goal and phase; do not merge superseded scope back into the release. Completed phases stay complete. Reopen one only when a named event invalidates its evidence, such as a Code SHA change, a non-changelog Release SHA change, or a workflow fix that the existing parent run cannot consume.

Respect release guardrails

• Do not change version numbers without explicit operator approval.
• When normal beta/stable release planning includes a backport audit, read references/backport-discovery.md before selecting commits. Freeze the release baseline and main SHA, complete the durable candidate ledger, and get approval for its categorized set before mutating the release branch. This audit is required for discovery; it does not authorize optional backports on an already-frozen candidate.
• Versions use YYYY.M.PATCH, where PATCH is the sequential release-train number within the month, not the calendar day.
• Choose a new beta train from stable and beta releases only. Alpha-only tags do not consume or advance the beta/stable patch number. Continue the highest existing unpublished/published beta train with the next beta.N when appropriate; otherwise increment the highest stable/beta patch by one and start at beta.1.
• Example: after stable 2026.6.5, the next new beta train is 2026.6.6-beta.1, even if automated alpha-only tags such as 2026.6.10-alpha.1 exist.
• Obtain explicit operator approval before the first irreversible publish action. Instructions to cut, ship, publish, or get a named release out carry through that release's validated publish and verification steps; do not ask again at final dispatch. Reconfirm only if the target version, tag, channel, publish scope, or a material risk changes.
• This skill should be sufficient to drive the normal release flow end-to-end.
• Use the private maintainer release docs for credentials, recovery steps, and mac signing/notary specifics, and use docs/reference/RELEASING.md for public policy.
• Core openclaw publish is manual workflow_dispatch; creating or pushing a tag does not publish by itself.
• Do not edit the root README.md as release prep, release closeout, or a substitute for release notes. Package-root README validation is a hard packaging gate, but a release only changes README content when an actual user-facing documentation contract changed.
• Normal release work happens on a branch cut from main, not directly on main. Use release/YYYY.M.PATCH for the branch name.
• Hold release scope from cut-SHA selection through publish and verification. The active release is the work queue; moving main is only a trusted workflow and provenance source unless the operator explicitly requests main work.
• Touch main during the active release only for an operator-requested change or a critical main-owned blocker that prevents this release and cannot be fixed or proven from the release branch. Examples include a live installer or trusted workflow that is sourced only from main. A red unrelated main check, baseline, refactor, cleanup, or later improvement is not a release blocker.
• Do not broaden a release-critical main fix to make moving main green. Keep the change to the exact blocker, run focused proof, follow the required main landing policy, then return immediately to the release branch. If unrelated main health blocks that landing, report the blocker and continue independent release work instead of adopting the failure.
• Defer normal forward-ports and main closeout until after publication. Forward-port before publish only when the operator requests it or main itself owns the exact release-critical runtime or workflow surface.
• If the operator asks for a release without saying stable/full, default to beta only. Continue from beta to stable only when the operator explicitly asks for the full release or an automated beta-and-stable train.
• Resolve the intended cut SHA once. If the operator supplies a SHA, use it exactly; do not pull, rebase, or advance it to newer main. Otherwise fetch origin/main once and record the selected full SHA plus its CI state. A red unrelated main check does not authorize healing main.
• Create a clean release worktree and release/YYYY.M.PATCH from that selected SHA. Do not commit or absorb unrelated dirty files as release preparation. Finish version preparation plus any operator-selected backports, release-only fixes, and explicitly required pre-publish main changes. Backports are optional. Freeze this product-complete tree as the Code SHA without changing the release changelog.
• Full product validation belongs to the Code SHA. If validation finds a code defect, fix it, freeze a new Code SHA, and validate that SHA. If the failure belongs to trusted workflow tooling, the harness, credentials, or infrastructure, repair the smallest owning surface and rerun against the same Code SHA. Touch main only under the active release scope lock above. Never mutate the release candidate to satisfy newer tooling or heal unrelated main.
• Apply a release firebreak after the Code SHA is frozen. Admit only confirmed product defects, package/provenance defects in the bytes to publish, security defects, or failures that make publication impossible. Queue adjacent improvements and broad confidence findings for the next beta or postpublish work.
• Operate with one release owner, one transition-only watcher, and at most one investigator for the current failed surface. One diagnosis, one fix when needed, and one narrow retry consume the failure budget; then reassess.
• Generate CHANGELOG.md only after the Code SHA is green. The resulting Release SHA must be a descendant whose complete diff from the Code SHA is exactly CHANGELOG.md. Release-note checks, npm preflight/package bytes, install/update acceptance, tagging, and publication run against the Release SHA. Full product validation is reused through the changelog-only-release-v1 evidence policy; any non-changelog source change returns to the Code SHA loop.
• During release planning, inspect both src/plugins/compat/registry.ts and src/commands/doctor/shared/deprecation-compat.ts before branching and again before final publish. For every deprecated compatibility record whose removeAfter date is on or before the release date, either remove the compatibility path where safe and validate the affected tests, or change it to removal-pending, document the blocker, and get explicit maintainer approval. Revalidate every due removal-pending record's blocker and upgrade conditions before shipping; keep it only with explicit maintainer approval until those conditions are met.
• When removing deprecated runtime/config compatibility, preserve any doctor migration, repair, or hint that is still needed by supported upgrade paths. Doctor-side compatibility should stay tracked in src/commands/doctor/shared/deprecation-compat.ts until maintainers confirm the repair is no longer needed.
• Revalidate compatibility replacement text during release planning. The recommended replacement can shift as plugin ownership, externalization, and config footprint move, so do not blindly copy stale replacement annotations into release notes.
• Do not delete or rewrite beta tags after their matching npm package has been published. If a pushed beta tag fails before npm publish, the version is not consumed: keep the same -beta.N, delete/recreate or force-move the git tag and prerelease to the fixed commit, and rerun preflight. Do not increment to the next beta number until the matching npm package has actually published. If a published beta needs a fix, commit the fix on the release branch and increment to the next -beta.N.
• For a beta release train, keep Full Release Validation as a pre-publish Code SHA gate unless the operator explicitly waives it. Run independent validation lanes in parallel where safe, but do not start changelog or package finalization until the Code SHA is green. After the changelog-only Release SHA exists, run npm preflight and the package/install/update acceptance roster against its exact bytes. If a product defect appears, return to a new Code SHA; if a release-tooling or publication child fails, repair/resume that child without changing the candidate. After a published beta needs a code fix, increment the beta number and repeat. Defer its forward-port until after publication unless the operator requests it. Do not scan moving main for extra fixes during an active release unless the operator explicitly asks for that audit. Operators may authorize up to 4 autonomous beta attempts; after 4 failed beta attempts, stop and report.
• As soon as the Code SHA exists, dispatch OpenClaw Performance with target_ref=<code-sha> in parallel with the other release work. Do not wait for full release validation to start the performance signal.
• Before publish/closeout, compare available product performance metrics with earlier releases: Kova agent-turn/resource metrics, gateway startup ready/listen/RSS/CPU metrics, and CLI startup metrics from release evidence or clawgrit reports. Report regressions explicitly. A major regression is a release blocker unless the operator waives it or the data clearly proves infrastructure noise.
• Heal release-owned CI before changelog, tagging, or publishing. The exact Code SHA must have green Full Release Validation, including the root Dockerfile/install-smoke path. Treat a red Docker, package, or release workflow lane as a release-branch defect until the smallest correct fix is landed and proven; do not waive it because npm preflight or another sibling lane passed. Unrelated moving-main failures are not part of this gate.
• Keep the canonical scripts/pr runner authoritative for prepare and merge artifacts. A release-gate policy change may use focused candidate tests and exact-SHA hosted CI for proof, but never route prepare-* or merge-* through PR-controlled scripts or synthesize prepare artifacts to bootstrap the change. If the current canonical gate cannot validate the new policy, stop for explicit maintainer direction rather than weakening that boundary.
• In maintainer Testbox mode, use OPENCLAW_TESTBOX=1 scripts/pr prepare-run <PR> only after the exact PR head has passed CI and every scheduled hosted gate. For a workflow change, that means Blacksmith Testbox, Blacksmith ARM Testbox, Blacksmith Build Artifacts Testbox, and Workflow Sanity; only gates GitHub actually scheduled for that exact head are required. This preserves the canonical prepare artifacts while avoiding a redundant broad local suite. A literal CHANGELOG.md-only head gets a clean diff check instead because those workflows intentionally do not dispatch. Documentation and README changes still require CI. If merge-run requires a mainline sync, run OPENCLAW_TESTBOX=1 scripts/pr prepare-sync-head <PR>, wait for those hosted gates on the newly pushed SHA, then run prepare-run again.
• If an exact PR-head CI run has no active jobs because Blacksmith capacity is stalled, a maintainer may dispatch the explicit GitHub-hosted fallback from the PR head branch. First verify its workflow carries the current schema with gh api 'repos/openclaw/openclaw/contents/.github/workflows/ci.yml?ref=<pr-head-branch>' --jq .content | base64 --decode | rg -q 'pull_request_number:'. If absent, refresh the PR head from main, use the new SHA, and let normal CI run before considering another fallback. Then dispatch: gh workflow run ci.yml --repo openclaw/openclaw --ref <pr-head-branch> -f target_ref=<full-pr-sha> -f pull_request_number=<pr-number> -f include_android=true -f release_gate=true. Use it only for an observed provider queue stall, never for failed CI or as a routine shortcut. The run must be named CI release gate <full-pr-sha> and pass on that exact SHA; the native hosted-gate verifier rejects generic manual CI runs. If Blacksmith Build Artifacts Testbox is the only remaining required gate and it is still queued without a runner, the same completed fallback CI may cover it because its build-artifacts job builds, packages, and smoke tests those artifacts. The verifier records that coverage. Never use this coverage when the artifact workflow has started, failed, been cancelled, or been skipped. Then rerun OPENCLAW_TESTBOX=1 scripts/pr prepare-run <PR>.
• Generate the changelog once after the final Code SHA is fully green. Do not regenerate it for same-candidate tooling reruns, resumed publication, or promotion. If code changes, validate the replacement Code SHA first and then regenerate the release section once for that new history. Use $openclaw-changelog-update for the rewrite. Do not continue release prep if the target CHANGELOG.md section does not have ### Highlights, ### Changes, and ### Fixes, grouped by user-facing surface while preserving every relevant PR/issue ref and every human Thanks @... attribution in the grouped bullet.
• Changelog PR provenance follows origin/main, not the release integration PR. Cite the original merged main PR for equivalent backports. Keep a release-branch PR only when the change landed there first and has not yet been forward-ported to main.
• Do not create beta-specific CHANGELOG.md headings. Beta releases use the stable base version section, for example v2026.4.20-beta.1 uses ## 2026.4.20 release notes.
• When any beta, stable, or extended-stable release is live, make a best-effort Discord announcement using the release-track-specific wording; do not block or roll back the release if the announcement fails.
• When asked to announce on X, use ~/Projects/bird/bird and follow the release tweet style below.

Prepare extended-stable backports

When asked to create the initial .33 extended-stable line or a later maintenance patch, read references/backport-discovery.md and references/extended-stable-backports.md and follow both before version, tag, or publication work. Treat backport discovery and preparation as an ability of this release skill, not as a separate release workflow.

The backport flow covers mainline inventory, private-security reconciliation, approval, the staging PR, and proof handoff. After it lands, use the sequence below. Never route .33+ through regular beta/stable release steps.

Extended-stable requires a visible SDK/config backport warning whenever a candidate changes the public plugin SDK or a config/default/schema/migration surface. Prefer an adaptation that uses the SDK and configuration already shipped on that line. If a contract change remains necessary, record its published impact and the maintainer decision in the ledger and staging PR. Read references/extended-stable-backports.md; a clean cherry-pick, green release checks, or a regenerated baseline does not by itself explain the maintenance risk.

Publish Gateway extended-stable releases

Use this path only for the trailing completed month's .33+ Gateway distribution: the openclaw npm package, official npm plugins, and matching Docker Gateway images. Treat docs/reference/RELEASING.md, scripts/openclaw-npm-extended-stable-release.mjs, and the release workflows on pinned current main as the exact command and validation contract.

1. On extended-stable/YYYY.M.33, verify the root and every publishable official plugin have the intended version. Generate and commit the complete ## YYYY.M.P changelog section with ### Highlights, ### Changes, and ### Fixes. Carry the full current-main Docker release-channel unit: workflow, promoter, policy, shared classifier, tests, and workflow validation. Run focused checks and freeze the untagged tip SHA.
2. From that branch, run npm preflight with the SHA as tag, preflight_only=true, and npm_dist_tag=extended-stable; save the run ID.
3. Run complete Full Release Validation against the canonical branch with release_profile=stable; save its run ID and successful run_attempt. Prefer the trusted main-pinned harness, which attests the immutable target SHA in its v3 manifest. Any candidate branch change invalidates both gates.
4. Require the tip still equals the frozen SHA, then create signed vYYYY.M.P. Never move or delete a final tag; later source changes need a new patch.
5. Require the saved validation run to be complete and successful, bind its manifest target SHA and attempt to the tag, and accept a direct run from the canonical branch, a direct current-main run whose workflow SHA is still reachable from main, or a trusted main-pinned release-ci/* harness. Reject narrow reruns.
6. Dispatch plugin-npm-release.yml from the same branch with publish_scope=all-publishable, the full release SHA as ref, and npm_dist_tag=extended-stable. Require complete exact-version and selector readback, then save the successful plugin run ID.
7. Publish core with the tag, npm_dist_tag=extended-stable, all three run IDs, and full_release_validation_run_attempt=<saved-attempt>. Normally dispatch from the canonical branch. For a workflow-only recovery after the candidate is immutable, dispatch trusted current main with release_candidate_branch=extended-stable/YYYY.M.33; it still publishes the tag checkout and accepts canonical-branch, current-main, or trusted-pinned validation evidence; the prepared tarball and every evidence identity must still match the candidate SHA.
8. From a clean current-main checkout, run node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.P. Verify signatures, provenance, inventories, exact versions, and selectors. Use the generated repair only for the root selector; repair other selectors with approved credential-isolated tooling. Never republish a version.

Keep release channel naming aligned

• stable: user updates resolve npm latest; tagged regular releases publish to npm beta by default, then operators may target or promote to latest explicitly
• extended-stable: user updates resolve npm extended-stable; operators publish the trailing completed month's .33+ line from extended-stable/YYYY.M.33
• beta: prerelease tags like vYYYY.M.PATCH-beta.N, with npm dist-tag beta
• Prefer -beta.N; do not mint new -1 or -2 beta suffixes
• dev: moving head on main
• When using a beta Git tag, publish npm with the matching beta version suffix so the plain version is not consumed or blocked

Close stable releases on main

This gate starts only after stable publication. It is a narrow shipped-state closeout, not permission to heal broader main. Stable publication is not complete until main carries the actual shipped release state.

1. Start from fresh latest main. Audit release/YYYY.M.PATCH against it and forward-port real fixes that are absent from main. Do not blindly merge release-only compatibility, test, or validation adapters into newer main.
2. Set main to the shipped stable version, not a speculative next train. Run pnpm release:prep after the root version change, then pnpm deps:npm-lock:check.
3. Make CHANGELOG.md's ## YYYY.M.PATCH section on main exactly match the tagged release branch. Include the stable appcast.xml update when the mac release published one.
4. Do not add YYYY.M.PATCH+1, a beta version, or an empty future changelog section to main until the operator explicitly starts that release train.
5. Run pnpm release:generated:check, pnpm deps:npm-lock:check, and OPENCLAW_TESTBOX=1 pnpm check:changed. Push, then verify origin/main contains the shipped version and changelog before calling the stable release done.
6. Keep repository variables RELEASE_ROLLBACK_DRILL_ID and RELEASE_ROLLBACK_DRILL_DATE current after each private rollback drill. openclaw-stable-main-closeout.yml starts from the main push carrying the shipped version, changelog, and appcast after stable publication, then binds immutable evidence to the published tag. Do not declare stable complete until it writes the immutable closeout manifest to the GitHub release. The drill must be within 90 days; manual dispatch is only for repair/replay, and private rollback commands remain in the maintainer-only runbook.

Handle versions and release files consistently

Use the release preparation controller before manual version edits:

pnpm release:prepare -- --version YYYY.M.PATCH-beta.N --shadow
pnpm release:prepare -- --version YYYY.M.PATCH-beta.N --write
pnpm release:prepare -- --version YYYY.M.PATCH-beta.N --check

Shadow mode is the default and never runs mutating commands. Write mode aligns the root and macOS versions, optionally Android with --android, then runs only the version-owned generated metadata DAG. Every mode writes an exact HEAD/worktree-bound manifest under git metadata for cutover review.

• Version locations include:
  • package.json
  • apps/android/app/build.gradle.kts
  • apps/ios/Sources/Info.plist
  • apps/ios/Tests/Info.plist
  • apps/macos/Sources/OpenClaw/Resources/Info.plist
  • docs/install/updating.md
  • Peekaboo Xcode project and plist version fields
• Before creating a release tag, make every version location above match the version encoded by that tag.
• For fallback correction tags like vYYYY.M.PATCH-N, the repo version locations still stay at YYYY.M.PATCH.
• “Bump version everywhere” means all version locations above except appcast.xml.
• Release signing and notary credentials live outside the repo in the private maintainer docs.
• Every stable OpenClaw release ships the npm package, macOS app, and signed Windows Hub installers together. Beta releases normally ship npm/package artifacts first and skip native app build/sign/notarize/promote unless the operator requests native beta validation.
• Do not let the slower macOS signing/notary path block npm publication once the npm preflight has passed. Keep mac validation/publish running in parallel, publish npm from the successful npm preflight, then start published npm install/update, Docker, and Parallels verification while mac artifacts continue.
• After a beta is published, overlap remote/manual release rosters where useful, but avoid piling local Docker, Parallels, and QA-Lab work onto the same host when it would create system-load noise. Use selective reruns after failures or fixes, but keep proof that Docker, Parallels, and QA-Lab each passed at least once before stable/latest promotion.
• Mac packaging may be built from a slight release-branch variation of the tagged commit when the delta is mac packaging, signing, workflow, or validation-only release machinery. If mac packaging needs release-branch-only fixes after the stable npm package or GitHub tag is already published, do not create a vYYYY.M.PATCH-N correction tag just to change the workflow source. Dispatch the release-ops mac workflows for the original tag=vYYYY.M.PATCH with source_ref=release/YYYY.M.PATCH and public_release_branch=release/YYYY.M.PATCH; provenance checks must prove the source SHA descends from the tag and validation/preflight use the same source. Reserve vYYYY.M.PATCH-N correction tags for emergency hotfixes that must publish a new npm package/release identity, not for ordinary mac-only packaging recovery.
• The production Sparkle feed lives at , and the canonical published file is on in the repo.

Build changelog-backed release notes

• CHANGELOG.md is release-owned. Normal PRs and direct main fixes should not edit it.
• After the product-complete Code SHA passes Full Release Validation, rewrite the target CHANGELOG.md section from history, not existing notes. Use the last reachable stable or beta release tag as the base, then inspect every commit through the Code SHA. This is the one release-note mutation that creates the Release SHA.
• Generate $openclaw-changelog-update's full contribution manifest before the editorial rewrite. It is the required source for ### Highlights, ### Changes, and ### Fixes; do not preserve old grouped prose without comparing it to the manifest's PRs, contributors, direct commits, and unlinked commits.
• A same-Code-SHA retry reuses the existing changelog. A new beta containing code changes must first validate its replacement Code SHA, then refresh the same stable-base ## YYYY.M.PATCH section once.
• Always fetch and pass current origin/main as the canonical main ref. Equivalent release/backport PRs are omitted in favor of the original merged main PR. A release-branch PR remains only until that change is forward-ported.
• Include both merged PR commits and direct commits on main. Direct commits matter: infer notes from their subject, body, touched files, linked issues, tests, and nearby code when no PR body exists.
• Keep direct commits in the generated manifest and use them to shape grouped user outcomes, but never dump them into CHANGELOG.md or GitHub release bodies. The public complete record is PR-first and exhaustive for PRs.
• Prefer PR bodies, issue links, review proof, and commit bodies over commit subjects alone. If a commit fixed an issue directly, the commit body should name the user-visible behavior, affected surface, issue ref, and credited reporter/contributor when known.
• Treat missing context as a release-note audit gap: inspect the diff and linked issue, draft the best accurate entry, and note the uncertainty for maintainer review rather than inventing impact.
• Add missed user-facing changes, remove internal-only noise, dedupe overlapping PR/direct-commit entries, and sort each section from most to least interesting for users.
• Group related highlights, changes, and fixes by user-facing surface and impact, but never lose traceability: each grouped bullet keeps every relevant #issue, (#PR), Fixes #..., and every human Thanks @... handle. Multiple thanks in one bullet are expected when multiple contributor PRs are grouped.

Write release tweets

Use the OpenClaw account's existing release-post style:

• Format: OpenClaw YYYY.M.PATCH 🦞 or 🦞 OpenClaw YYYY.M.PATCH is live, blank line, then 3-4 emoji-led bullets, blank line, one short punchline, then the release link.
• For beta: say OpenClaw YYYY.M.PATCH-beta.N 🦞 or OpenClaw YYYY.M.PATCH beta N is live; keep it clearly beta and avoid implying stable promotion.
• Lead with user-visible capabilities, then important integrations, then reliability/security/install fixes. Compress "lots of fixes" into one readable bullet.
• Read the full changelog section before drafting. Do not lead with coverage, CI, validation, or internal release mechanics unless the release is explicitly about those. Peter prefers concrete user wins: features, integrations, workflow improvements, and practical reliability fixes.
• Do not feature QA parity, test coverage, release gates, or validation lanes in user-facing launch tweets. Keep them for release notes or maintainer proof unless the operator explicitly asks for validation-focused copy.
• Do not feature plugin-author or developer tooling such as SDK helpers, tool-plugin scaffolding, build/validate/init commands, or internal CLI plumbing in general user-facing launch tweets unless the operator explicitly asks for developer-focused copy.
• Tone: high-signal, slightly cheeky, confident, not corporate. One joke is enough. Avoid punching down, insulting users, or promising what was not verified.
• Peter likes dry, compact taglines when they feel earned. Good example: Big release, tiny release notes... kidding. Keep the joke short and let the feature bullets carry the tweet; do not turn the punchline into a second paragraph or a forced bit.
• Length: release tweets are always standard tweets under 280 characters, with room for one URL. Trim to 3-4 bullets and count the final text before posting.
• Links/media: include the GitHub release or changelog link at the end of the first release tweet.
• Thread follow-ups: if doing a thread, keep the first release tweet as the compact launch post, then publish one focused feature explainer per reply. Follow-up replies should not repeat "new in VERSION" or the version number when the thread context already makes it obvious.
• Peter's preferred thread workflow: first agree on the generic launch tweet, then proceed through follow-up tweets one by one. When he says next, provide or copy the next follow-up only; do not dump the full thread again unless asked.
• Every follow-up tweet should include a docs URL for that specific feature. Prefer a bare URL over Docs: <url> unless the label is needed for clarity. Keep follow-ups concise: around 160-220 raw characters is usually the sweet spot; under 280 is the hard cap. If a URL makes a tweet fail, trim prose before dropping the URL. Prefer explaining diagnostics, trajectory/export, provider setup, model commands, or other setup-heavy features in follow-ups instead of overloading the first release tweet.

Examples to adapt:

OpenClaw 2026.4.20-beta.1 🦞

🐳 Docker install/update smoke
🖥️ Parallels upgrade checks
🔧 Package verification tightened

Beta first. Stable after the gauntlet.
<release link>

OpenClaw 2026.4.20 🦞

🚀 Faster install + update
🐳 Docker + Parallels verified
🍎 macOS signed + notarized
🔧 Channel/plugin fixes

Good boring release. Best kind.
<release link>

Packaging issue in 2026.4.20-beta.1.

2026.4.20-beta.2 fixes install/update verification. No tag rewrites; beta moves
forward.

Upgrade with the beta channel.
<release link>

Run publish-time validation

Before tagging or publishing, run:

pnpm release:fast-pretag-check
pnpm check:architecture
pnpm build
pnpm ui:build
pnpm qa:otel:smoke
pnpm release:check
pnpm test:install:smoke

• Treat pnpm release:fast-pretag-check as a hard packaging gate. Every publishable plugin must have a non-empty package-root README.md, build its package-local runtime, and pass the npm and ClawHub release metadata checks before a tag or publish workflow can start. Do not defer README, entrypoint, or packed-artifact failures to postpublish verification.
• Before generating the changelog, require green CI for the exact Code SHA, not an earlier branch SHA. Heal every related red CI, release-check, packaging, or root-Dockerfile lane on the release branch and rerun the affected exact-SHA gates. Defer product-fix forward-ports until after publication unless the active release scope lock requires an exact main-owned blocker fix. Never waive a red Docker lane because npm preflight passed.
• Root Dockerfile proof is mandatory on the Code SHA before every beta and stable tag. The changelog-only Release SHA reuses that product proof, while exact Release SHA npm preflight and package/install acceptance prove the changed package bytes. The tag-triggered Docker Release workflow is post-tag publishing, not the first valid proof that the root Dockerfile can build.
• Before tagging, diff publishable plugin package manifests against the last reachable stable/beta release tag. For every newly publishable package (openclaw.release.publishToNpm: true or publishToClawHub: true) whose package name did not exist in the base tag, verify the target registry package already exists in npm/ClawHub or stop and help the owner mint/prepublish the package first. Do not hide or disable release surfaces just to unblock a train unless the owner explicitly decides the plugin should not ship in that release; first-package registry ownership is release prep, not product rollback. The mint/prepublish path must either be the real release publish path for the auto-bumped beta version, or a deliberately non-consuming registry-prep step that cannot occupy the next beta version/tag. Confirm registry owner, npm scope/package-creation permission, provenance path, and first-package publish plan before the full release publish continues. Useful npm probe: npm view <package-name> version dist-tags --json --prefer-online; a 404 for a package newly added to the release is a release-prep blocker, not something to discover from the publish job.
• Bootstrap a new ClawHub package only from the trusted workflow source: gh workflow run plugin-clawhub-new.yml --ref main -f plugins=@openclaw/name -f ref=<full-release-sha> -f pretag_validation=true -f dry_run=true. The workflow source stays on main; ref is the exact release target. A pre-tag dry run rejects tag/parent-approval inputs and requires the target to be reachable from main or release/*. It must still resolve the live registry plan, pack every candidate, upload and download the exact artifact ID, rehash the inventory, reject ambiguous TAR paths locally with the pinned CLI's USTAR canonicalization, and validate each tarball with the pinned CLI publish dry-run. It never loads credentials or changes package/trusted-publisher state. Approve the environment only after the secretless pack jobs finish; the protected validation job itself has no credentials or mutation commands. For an existing version missing trusted-publisher configuration, pack the target bytes too and require its tag plus exact registry byte/metadata equality before allowing configuration-only repair. The credential-job prefilter enforces the ClawHub 120 MiB compressed and 50 MiB total-payload limits, plus 64 MiB expanded-TAR and 10,000-TAR-entry parser-safety limits. A mismatch requires a new version; never bless unrelated immutable bytes. A real run publishes the exact downloaded tarball, bounds each CLI attempt, and records byte-identical registry readback. Final release verification must consume the unique terminal readback artifact and bind its main-only workflow SHA/attempt, target SHA, requested packages, package artifact ID/name/digest, and per-package SHA-256/size/npm integrity metadata. The parent approval attests a separate exact trusted-main child workflow SHA; the child run and protected approval must match it. Rerun-failed recovery may reuse a prior package artifact only when the exact producer job succeeded. Final evidence must also preserve the locked ClawHub version, lock SHA-256, and npm integrity.

For a non-root smoke path:

  OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke

After npm publish, run:

node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>

• This verifies the published registry install path in a fresh temp prefix.
• For stable correction releases like YYYY.M.PATCH-N, it also verifies the upgrade path from YYYY.M.PATCH to YYYY.M.PATCH-N so a correction publish cannot silently leave existing global installs on the old base stable payload.
• Treat install smoke as a pack-budget gate too. pnpm test:install:smoke now fails the candidate update tarball when npm reports an oversized unpackedSize, so release-time e2e cannot miss pack bloat that would risk low-memory install/startup failures.
• Keep direct npm global coverage enabled in install smoke. It exercises plain npm install -g <candidate> fresh installs and npm-driven update installs, because many users install with npm even when docs prefer pnpm.
• Use pnpm test:live:media video for bounded video-provider smoke when video generation is in release scope. The default video smoke skips fal, runs one text-to-video attempt per provider with a one-second lobster prompt, and caps each provider operation with OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS (180000 by default).
• Run pnpm test:live:media video --video-providers fal only when FAL-specific proof is required. Its queue latency can dominate release time.
• Set OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 only when intentionally validating the slower image-to-video and video-to-video transform lanes.

Check all relevant release builds

• Always validate the OpenClaw npm release path before creating the tag.
• Use the configured secret workflow before live release validation so OpenAI and Anthropic credentials are available without printing secrets.
• Parallels validation and any local live model QA for this train must use both OPENAI_API_KEY and ANTHROPIC_API_KEY. If either cannot be injected, stop before starting those local long lanes and report the missing key.
• Postpublish credentialed channel QA is the GitHub Actions workflow QA-Lab - All Lanes (.github/workflows/qa-live-transports-convex.yml), not a local substitute. Dispatch it from Actions against the published release tag during postpublish confidence. Use a SHA only when it satisfies the workflow's secret-bearing trust gate: main ancestor or open PR head. It runs the QA Lab mock parity gate plus live Matrix and live Telegram lanes using the qa-live-shared environment; Telegram uses Convex CI credential leases.
• Default release checks:
  • pnpm check
  • pnpm check:test-types
  • pnpm check:architecture
  • pnpm build
  • pnpm ui:build
  • pnpm release:check
  • OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke
• Release validation phases:
  • beta-publish: release_profile=beta, run_release_soak=false. This is the bounded prepublish gate; it excludes broad live/E2E, QA-live, and Parallels confidence work.
  • postpublish-confidence: run against the exact published beta package with run_release_soak=true or explicit focused groups. This is the default home for QA-live, broad Docker/live E2E, mobile, and Parallels.
  • stable-publish: release_profile=stable; require the stable publish roster and accepted confidence evidence.
• Post-published beta verification roster:
  • node --import tsx scripts/openclaw-npm-postpublish-verify.ts <beta-version>
  • install/update smoke against the published beta channel
  • Docker install/update coverage that exercises the published beta package
  • published npm Telegram proof: dispatch Actions > NPM Telegram Beta E2E from main with and , and require success. This workflow is maintainer-dispatched and intentionally has no approval gate; only supplies the shared QA secrets. This is the default button path for installed-package onboarding, Telegram setup, and real Telegram E2E against the published npm package. Use the local lane with the matching and Convex CI env only as a fallback or debugging path.

Use the right auth flow

• OpenClaw publish uses GitHub trusted publishing.
• Stable npm promotion from beta to latest uses the restricted release-ops openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml workflow because npm dist-tag management needs NPM_TOKEN, while the public npm release workflow stays OIDC-only.
• Prefer fixing the release-ops workflow token path over any local 1Password fallback. The desired setup is a granular npm token stored as the release-ops repo's NPM_TOKEN secret, scoped to the openclaw package with read/write and 2FA bypass for automation.
• If the release-ops dist-tag workflow cannot promote because NPM_TOKEN is absent or stale, use the local tmux + 1Password fallback:
  • Start or reuse a tmux session so interactive npm login and OTP prompts are observable and recoverable.
  • Hard rule: never run op directly in the main agent shell during release work. Any 1Password CLI use must happen inside that tmux session so prompts and alerts are contained and observable.
  • Use $release-private for the npm credentials and OTP item. Do not print passwords, tokens, or OTPs to the transcript; send them through tmux buffers, env vars scoped to the tmux command, or expect with log_user 0.
  • Re-authenticate npm inside that tmux session with npm login --auth-type=legacy, then confirm npm whoami reports steipete.
  • Promote with a fresh OTP: npm dist-tag add [e-mail] latest --otp "$OTP".
  • Verify with a cache-bypassed registry read, for example: npm view openclaw dist-tags --json --prefer-online --cache /tmp/openclaw-npm-cache-verify-$$ and npm view openclaw@latest version dist.tarball --json --prefer-online.
• Direct stable publishes can also use that release-ops dist-tag workflow to point beta at the already-published latest version when the operator wants both tags aligned immediately.
• The publish run must be started manually with workflow_dispatch.
• The npm workflow and the release-ops mac publish workflow accept preflight_only=true to run validation/build/package steps without uploading public release assets.
• Real npm publish requires a prior successful npm preflight run id plus the successful Full Release Validation run id and exact run attempt for the same tag/SHA so the publish job promotes the prepared tarball instead of rebuilding it and attaches the correct release evidence.

Fallback local mac publish

• Keep the original local macOS publish workflow available as a fallback in case CI/CD mac publishing is unavailable or broken.
• Preserve the existing maintainer workflow Peter uses: run it on a real Mac with local signing, notary, and Sparkle credentials already configured.
• Follow the private maintainer macOS runbook for the local steps: scripts/package-mac-dist.sh to build, sign, notarize, and package the app; manual GitHub release asset upload; then scripts/make_appcast.sh plus the appcast.xml commit to main.
• scripts/package-mac-dist.sh now fails closed for release builds if the bundled app comes out with a debug bundle id, an empty Sparkle feed URL, or a CFBundleVersion below the canonical Sparkle build floor for that short version. For correction tags, set a higher explicit APP_BUILD.
• scripts/make_appcast.sh first uses generate_appcast from PATH, then falls back to the SwiftPM Sparkle tool output under apps/macos/.build.
• For stable tags, the local fallback may update the shared production appcast.xml.
• For beta tags, the local fallback still publishes the mac assets but must not update the shared production appcast.xml unless a separate beta feed exists.
• Treat the local workflow as fallback only. Prefer the CI/CD publish workflow when it is working.
• After any stable mac publish, verify all of the following before you call the release finished:
  • the GitHub release has .zip, .dmg, and .dSYM.zip assets
  • appcast.xml on main points at the new stable zip
  • the packaged app reports the expected short version and a numeric CFBundleVersion at or above the canonical Sparkle build floor

Run the release sequence

1. Confirm release intent once. Treat prior explicit instructions to cut, ship, publish, or complete the named release as continuing authorization through publish and verification. Reconfirm only if the release identity, channel, publish scope, or material risk changes.
2. Choose the exact target version, git tag, and npm dist-tag (beta or latest).
3. Start from a clean release worktree. Do not absorb unrelated dirty files.
4. Resolve the cut SHA once. Use an operator-supplied SHA exactly; otherwise fetch origin/main once, record its full SHA and CI state, and do not chase a newer moving head.
5. Create release/YYYY.M.PATCH from that selected commit.
6. Make every repo version location match the beta tag. Apply only explicitly selected backports or release fixes. Make a pre-publish main change only under the active release scope lock. Freeze the result as the Code SHA.
7. Immediately dispatch Actions > OpenClaw Performance from the pinned trusted workflow source with target_ref=<code-sha>, profile=release, repeat=3, deep profiling off, live OpenAI off, and regression failure off. Let it run in parallel with Code SHA validation.
8. Run the deterministic source preflight, then Full Release Validation against the exact Code SHA with node scripts/full-release-validation-at-sha.mjs --sha <code-sha> --target-ref release/YYYY.M.PATCH. For beta-publish, keep release_profile=beta and run_release_soak=false. Record the Validation SHA + Tooling SHA tuple (Validation SHA is the Code SHA in this phase) and use one transition watcher. Product failures return to step 6 with a new Code SHA; tooling/harness/provenance, infrastructure/credential, and wrapper failures keep the Code SHA and rerun only the failed surface.
9. After the Code SHA is green, run /changelog once for the stable-base target version using current origin/main for canonical PR provenance. Keep the heading as ## YYYY.M.PATCH, not ## YYYY.M.PATCH-beta.N.
10. Commit only CHANGELOG.md and freeze the Release SHA. Verify <code-sha>..<release-sha> changes exactly CHANGELOG.md; any other path returns to step 6.
11. Dispatch Full Release Validation for the Release SHA with evidence reuse enabled. It must select changelog-only-release-v1, reuse the green Code SHA product matrix, and run no product lanes again.
12. Run npm preflight and release-note/package/install/update acceptance against the exact Release SHA and prepared tarball. A package or install failure that exposes a product defect returns to step 6; a tooling failure keeps the Release SHA unchanged.

GHSA advisory work

• Use openclaw-ghsa-maintainer for GHSA advisory inspection, patch/publish flow, private-fork validation, and GHSA API-specific publish checks.