feat(update): support extended-stable package updates by kevinslin · Pull Request #99811 · openclaw/openclaw

kevinslin · 2026-07-04T04:19:39Z

Related: #99352

What Problem This Solves

Operators need a supported way to install, persist, and inspect the trailing supported-month npm release without changing the existing stable channel, which already maps to npm latest. Before this change, the CLI had no canonical channel contract for that release line, no fail-closed exact resolution, and no safe Gateway or status behavior for it.

Why This Change Was Made

This adds extended-stable as a net-new package-only channel across config, CLI, status, Gateway handoff, and Package Acceptance. Foreground updates resolve the public npm selector, verify the selected exact package, reuse the existing downgrade and post-core commit boundaries, reject Git checkouts and tag overrides before mutation, and skip startup/background auto-update. Post-core plugin convergence temporarily targets the existing stable/latest plugin line; plugin publication remains out of scope.

The change is AI-assisted. I reviewed the implementation, its transaction boundaries, and the verification results.

User Impact

Package-install users can run openclaw update --channel extended-stable, persist that selection, use bare foreground updates afterward, and inspect availability with openclaw update status. Existing stable, beta, and dev defaults and mappings remain unchanged. Git users receive a structured non-mutating error, and missing or inconsistent public npm metadata never falls back to another release line.

Evidence

Flow doc: Extended-Stable CLI Update Flow.
Full CLI update suite: 174/174 passed.
Focused post-rebase policy matrix:
- 11 extended-stable CLI transaction cases passed.
- 4 resolver/runner exact-resolution and tag-guard cases passed.
- 87 startup, status, and channel-regression cases passed.
- 5 Gateway/handoff cases passed.
- Package Acceptance allowlist case for openclaw@extended-stable passed.
Config schema/help baselines, base schema generation, oxlint, formatting, MDX, markdownlint, docs map, and 5,550 internal links passed.
Review-added regression proof confirms selector failure does not modify config, package bytes, or the legacy launchd updater job; explicit and stored --tag overrides are rejected; managed handoff sentinel errors retain the exact selector reason.
Current public-registry prerequisite check returns HTTP 404 for openclaw@extended-stable, so the positive live-package run remains blocked until the publication workflow in feat(release): add monthly npm extended-stable publication #99352 ships the dist-tag. The implemented path and tests prove the required fail-closed selector_missing behavior for this state.
Two local type errors remain unchanged in untouched src/config/io.ts and src/secrets/config-io.ts; the worktree's private @openclaw/crabline bootstrap is also unavailable. Broad Testbox proof is delegated to PR CI because local Azure Crabbox auth returned 401 and the Blacksmith CLI is not installed.

Live fail-closed proof

On current head 7485b3573e, I ran the real CLI entrypoint from a package-style archive with no .git, an isolated HOME/state/config path, and public npm registry access:

$ node --import tsx src/entry.ts update --channel extended-stable --yes --json --timeout 30
{
  "status": "error",
  "mode": "unknown",
  "root": "/private/tmp/pr99811-proof.Ek2cLv/repo",
  "reason": "selector_missing",
  "steps": [],
  "durationMs": 0
}
$ echo "$?"
1
$ echo "CONFIG_BEFORE=$before CONFIG_AFTER=$after"
CONFIG_BEFORE=absent CONFIG_AFTER=absent

This is the current public-registry 404 path. The structured selector_missing result, empty mutation-step list, nonzero exit, and unchanged absent config prove the CLI fails before config or package mutation. Positive live update/status proof remains gated on #99352 publishing the extended-stable dist-tag; maintainers can either sequence the PRs or explicitly accept this fail-closed launch window.

Live local install and update proof

Revalidated on PR head 3c34c5af20 using loopback Verdaccio and combined canary source 1ac14c2823 (the PR head plus the fork-only publication harness). The harness published @kevins8/[email protected] and .34, then moved extended-stable from .33 to .34. Its safety record reports hostBinding: 127.0.0.1:4873 and officialNpmPublishAttempted: false.

Clean install passed:

$ npm install -g --prefix "$prefix" @kevins8/openclaw@extended-stable --registry http://127.0.0.1:4873/
$ openclaw --version
OpenClaw 2000.4.34

Real foreground update from the existing stable base passed:

$ openclaw --version
OpenClaw 2000.4.33
$ env NPM_CONFIG_REGISTRY=http://127.0.0.1:4873/ \
      npm_config_registry=http://127.0.0.1:4873/ \
      OPENCLAW_UPDATE_PACKAGE_SPEC=@kevins8/openclaw \
      openclaw update --channel extended-stable --yes --json --no-restart
{
  "status": "ok",
  "mode": "npm",
  "before": { "version": "2000.4.33" },
  "after": { "version": "2000.4.34" },
  "postUpdate": { "plugins": { "status": "ok", "changed": false } }
}
$ echo "$?"
0
$ openclaw --version
OpenClaw 2000.4.34

The update proof includes the staged npm install, scoped-package swap, mandatory openclaw doctor --non-interactive --fix with exit 0, and plugin convergence. Production behavior remains pinned to public npm; the alternate package/registry path activates only when OPENCLAW_UPDATE_PACKAGE_SPEC exactly matches the installed package and the configured registry is loopback.

clawsweeper · 2026-07-04T04:27:48Z

Codex review: needs maintainer review before merge. Reviewed July 4, 2026, 2:15 AM ET / 06:15 UTC.

Summary
The PR adds a package-only extended-stable update channel across config, CLI update/status/repair, Gateway handoff, startup/background update behavior, package acceptance docs, and tests.

PR surface: Source +404, Tests +707, Docs +64, Generated 0, Other -3. Total +1172 across 36 files.

Reproducibility: not applicable. this is a feature/config-channel PR rather than a broken existing behavior report. Current main lacks the channel, and the PR body plus live-output proof define the new fail-closed and loopback-positive behavior.

Review metrics: 2 noteworthy metrics.

Config surface: 1 enum value added. A new persisted update.channel value affects upgrades, status display, Gateway handoff behavior, docs, and operator expectations.
Release prerequisite: 1 open companion PR. Positive public package behavior depends on the npm extended-stable dist-tag work tracked in feat(release): add monthly npm extended-stable publication #99352.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/cli/update-cli.ts, serialized state: src/infra/update-check.test.ts, serialized state: src/infra/update-managed-service-handoff.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #99808
Summary: This PR is the implementation candidate for the foreground extended-stable update-channel issue; the monthly publication PR is a related prerequisite but owns a different release workflow surface.

Members:

canonical: [Feature]: Support foreground extended-stable package updates #99808 - The PR body uses closing syntax for the issue and implements the same CLI/config/status/Gateway behavior request.
partial_overlap: feat(release): add monthly npm extended-stable publication #99352 - That open PR owns publishing the npm extended-stable dist-tag consumed by this PR, but does not implement the CLI/config foreground update channel.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

[P1] The PR adds a new persisted update.channel value and package update path, so maintainers need to accept the upgrade/config contract before merge.
[P1] The public openclaw@extended-stable npm selector currently returns 404; maintainers should either sequence merge behind feat(release): add monthly npm extended-stable publication #99352 or explicitly accept the temporary fail-closed selector_missing window.
[P1] Post-core plugin convergence intentionally remains on the existing stable/latest plugin line for extended-stable, which is a product and release sequencing choice rather than a narrow code repair.

Maintainer options:

Sequence With Publication (recommended)
Wait for the companion publication path to create the public extended-stable dist-tag, then verify a positive package update/status run before merge.
Accept Fail-Closed Launch
Maintainers can merge CLI/config support first if they explicitly accept that early users will receive selector_missing until the dist-tag exists.
Pause Channel Direction
If maintainers do not want a new persisted update channel, pause or close this PR and keep operator targeting on raw package specs or another release mechanism.

Next step before merge

[P2] Protected label, new persisted channel contract, plugin-line choice, and release sequencing require maintainer decision rather than an automated repair lane.

Security
Cleared: The diff touches package update and registry-resolution code, but it adds exact-selector verification and does not add dependencies, lockfile changes, workflow permissions, or secret handling.

Review details

Best possible solution:

Land only after maintainers accept the new persisted package-only channel contract and either publish the public dist-tag or explicitly approve the temporary fail-closed behavior.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature/config-channel PR rather than a broken existing behavior report. Current main lacks the channel, and the PR body plus live-output proof define the new fail-closed and loopback-positive behavior.

Is this the best way to solve the issue?

Likely yes as an implementation shape: a dedicated package-only channel preserves the shipped stable equals npm latest contract and fails closed instead of falling back. Final acceptance still depends on maintainer product approval and release sequencing.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against d71a24f3a4b7.

Label changes

Label changes:

add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

P2: This is normal-priority release/update channel work with operator impact but no active outage shown.
merge-risk: 🚨 compatibility: The PR adds a persisted update.channel value and package update path that affects config, upgrades, Gateway handoff, and release sequencing.
rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes copied live CLI output for the public 404 fail-closed path and a loopback Verdaccio install/update path from 2000.4.33 to 2000.4.34.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied live CLI output for the public 404 fail-closed path and a loopback Verdaccio install/update path from 2000.4.33 to 2000.4.34.

Evidence reviewed

PR surface:

Source +404, Tests +707, Docs +64, Generated 0, Other -3. Total +1172 across 36 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	14	466	62	+404
Tests	13	729	22	+707
Docs	7	84	20	+64
Config	0	0	0	0
Generated	1	3	3	0
Other	1	3	6	-3
Total	36	1285	113	+1172

What I checked:

Repository policy applied: Root AGENTS.md was read and treats config/default/update/fallback changes as compatibility-sensitive; scoped docs, scripts, and Gateway guides were also read for touched paths. (AGENTS.md:31, d71a24f3a4b7)
Scoped guides applied: Scoped docs, scripts, and Gateway AGENTS.md files were read; no scoped rule added a line-level blocker for the docs, script helper, or Gateway update method changes. (src/gateway/AGENTS.md:1, d71a24f3a4b7)
No maintainer notes found: The checkout has no .agents/maintainer-notes directory, so there were no matching internal maintainer decisions to apply.
Current main lacks requested channel: Current main still defines UpdateChannel as only stable | beta | dev, so the central useful change is not already implemented. (src/infra/update-channels.ts:6, d71a24f3a4b7)
Latest release lacks requested channel: The latest release tag v2026.6.11 also defines only stable | beta | dev, so the new channel has not shipped. (src/infra/update-channels.ts:6, e085fa1a3ffd)
PR channel contract: PR head adds extended-stable to UpdateChannel, normalization, npm tag mapping, and beta-version channel preservation exclusions. (src/infra/update-channels.ts:6, 3c34c5af20f8)

Likely related people:

steipete: Introduced the dev update channel and later split the update CLI modules that own channel parsing and update execution. (role: feature history owner; confidence: high; commits: 4ebf55f1db82, 02684b913b48; files: src/infra/update-channels.ts, src/infra/update-runner.ts, src/infra/update-startup.ts)
vincentkoc: Recent history shows multiple update-check, startup, registry, and update-command repairs or commits around the same package update/status/finalize surfaces. (role: recent update/release contributor; confidence: high; commits: 86a28636fa80, 62fad3da8606, d68ca425bd98; files: src/infra/update-check.ts, src/infra/update-startup.ts, src/cli/update-cli/update-command.ts)
masatohoshino: Authored the recent effective git channel finalize repair that protects update-channel convergence from persisting or resolving the wrong channel. (role: adjacent finalize-path contributor; confidence: medium; commits: 085ff95fcf31; files: src/cli/update-cli/update-command.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1ba963e519

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

kevinslin · 2026-07-04T04:55:28Z

@clawsweeper re-review

clawsweeper · 2026-07-04T04:55:31Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

* feat(update): add extended-stable channel contract * feat(update): implement extended-stable package flow * docs(update): document extended-stable behavior * fix(update): preserve extended-stable preflight guarantees * fix(update): reject extended-stable Git repair * fix(update): support loopback extended-stable canaries * fix(update): preserve scoped package roots

* feat(update): add extended-stable channel contract * feat(update): implement extended-stable package flow * docs(update): document extended-stable behavior * fix(update): preserve extended-stable preflight guarantees * fix(update): reject extended-stable Git repair * fix(update): support loopback extended-stable canaries * fix(update): preserve scoped package roots (cherry picked from commit d214622)

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime cli CLI command changes scripts Repository scripts commands Command implementations size: XL maintainer Maintainer-authored PR labels Jul 4, 2026

chatgpt-codex-connector Bot reviewed Jul 4, 2026

View reviewed changes

Comment thread src/cli/update-cli/update-command.ts

clawsweeper Bot mentioned this pull request Jul 4, 2026

feat(release): add monthly npm extended-stable publication #99352

Merged

kevinslin added 5 commits July 4, 2026 12:23

feat(update): add extended-stable channel contract

3a3e4bc

feat(update): implement extended-stable package flow

b3023f9

docs(update): document extended-stable behavior

a489464

fix(update): preserve extended-stable preflight guarantees

f305616

fix(update): reject extended-stable Git repair

1240682

kevinslin added 2 commits July 4, 2026 12:24

fix(update): support loopback extended-stable canaries

011abf1

fix(update): preserve scoped package roots

bd68ef6

kevinslin force-pushed the dev/kevinlin/extended-stable-cli branch from 3c34c5a to bd68ef6 Compare July 4, 2026 19:24

kevinslin merged commit d214622 into openclaw:main Jul 4, 2026
96 checks passed

kevinslin deleted the dev/kevinlin/extended-stable-cli branch July 4, 2026 19:38

github-actions Bot mentioned this pull request Jul 4, 2026

📡 Upstream Digest — 2026-07-04 20:44 UTC curtismercier/openclaw-mods#1208

Open

This was referenced Jul 5, 2026

fix(watch): defer restart when dist/entry.js is missing mid-rebuild #99972

Merged

fix(telegram): strip standalone <parameter> wrappers in rich HTML sanitization (fixes #98557) #98604

Closed

fix(tui): queue prompts while the agent is busy #100123

Merged

This was referenced Jul 5, 2026

feat: publish plugins with extended-stable releases #100448

Merged

feat(update): notify extended-stable availability #100438

Merged

RomneyDa self-assigned this Jul 9, 2026

RomneyDa mentioned this pull request Jul 9, 2026

docs(skills): add backporting to release maintainer #99266

Merged

clawsweeper Bot mentioned this pull request Jul 11, 2026

fix(update): preserve local package overrides #89985

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(update): support extended-stable package updates#99811

feat(update): support extended-stable package updates#99811
kevinslin merged 7 commits into
openclaw:mainfrom
kevinslin:dev/kevinlin/extended-stable-cli

kevinslin commented Jul 4, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

kevinslin commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

kevinslin commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Live fail-closed proof

Live local install and update proof

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

kevinslin commented Jul 4, 2026

Uh oh!

clawsweeper Bot commented Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kevinslin commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading

clawsweeper Bot commented Jul 4, 2026 •

edited

Loading