fix(openclaw): validate runtime version output

[HOYALIM]

Summary

Replace positional openclaw --version parsing with validated semantic-version extraction. Decorated output now yields the actual version, while malformed output fails closed instead of influencing image upgrade and patch decisions.

Related Issue

Refs #5896.

Changes

• Add one executable semantic-version extractor used by the production Docker upgrade and patch-classification paths.
• Parse raw gateway version output through the existing TypeScript version parser during deployment verification.
• Exercise plain, decorated, multiline, and malformed output through the real shell boundary and deployment verification.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — internal image and verification parsing behavior; no command or configuration surface changes.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• npm run check:diff passed
• npx vitest run test/openclaw-version-parser.test.ts src/lib/verify-deployment.test.ts — 42 tests passed
• npm run build:cli and npm run typecheck:cli passed
• docker build --check -f Dockerfile . completed; six pre-existing secret-name warnings remained
• Linux bash:5.3 container execution extracted decorated output and rejected a malformed four-segment value
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Ho Lim subhoya@gmail.com

Summary by CodeRabbit

• Bug Fixes
  • Improved OpenClaw gateway version detection using a dedicated semantic-version parser for both plain and decorated openclaw --version output.
  • Deployment verification now returns no gateway version when openclaw --version fails or the output can’t be parsed.
  • Upgrade/patch decision logic now consistently relies on the same semantic-version extraction.
• New Features
  • Added a semantic-version extraction utility for OpenClaw-related version strings.
• Tests
  • Added unit tests for the version extraction utility (including fail-closed behavior).
  • Expanded deployment verification and integrity pin scenarios to cover parsing and command-failure cases.
• Chores
  • Container builds now fail fast when OpenClaw version detection can’t be determined.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

A shared SemVer extraction helper is added to the Docker image. OpenClaw build-time version checks and gateway verification now parse structured version output, with tests covering decorated, malformed, and failed responses.

Changes

OpenClaw version parsing

Layer / File(s)	Summary
SemVer helper and image integration scripts/extract-semver.sh, Dockerfile, test/openclaw-version-parser.test.ts, test/openclaw-integrity-pin-suite.ts	Adds strict SemVer extraction, installs it as an executable image helper, replaces Dockerfile version parsing, and tests supported, rejected, and failed version-command inputs.
Gateway version probe src/lib/verify-deployment.ts, src/lib/verify-deployment.test.ts	Parses raw openclaw --version output and returns null for malformed output or command failures.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested labels: refactor, platform: container, area: install, area: sandbox

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: validating OpenClaw runtime version output and failing closed on malformed values.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-onboard

1 optional E2E recommendation

• bootstrap-install-smoke

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Do not accept an unlabeled version for an OpenClaw command

• Location: src/lib/adapters/openshell/client.ts:98
• Category: correctness
• Problem: When the output has no `openclaw` token, `parseVersionFromText` returns the first semantic version. `fetchGatewayVersion` can therefore report a dependency or build-tool version as the gateway version.
• Impact: Deployment verification can display an incorrect OpenClaw version and hide malformed `openclaw --version` output.
• Recommendation: For calls that provide `openclaw --version`, return null when no OpenClaw-labeled line or bare-version output matches. Preserve generic fallback parsing only for callers that do not identify an executable.
• Verification: Add or inspect a `verifyDeployment` case where successful `openclaw --version` output is only `Dependency 1.2.3`; `gatewayVersion` must be null.
• Test coverage: A `verifyDeployment` test must assert that successful unlabeled semantic-version output returns `gatewayVersion: null`.
• Evidence: `fetchGatewayVersion` passes `openclaw --version` to `parseVersionFromText` in src/lib/verify-deployment.ts:213-217. src/lib/adapters/openshell/client.ts:98-99 falls back to the first semantic version when no executable token is found. The added deployment tests cover labeled decorated output, malformed labels, extra dotted components, and command failure, but not unrelated-version-only output.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Dockerfile`:
- Around line 301-302: Update both OpenClaw version-detection call sites around
CUR_VER and the corresponding second version variable to check the status of
openclaw --version and extract-semver explicitly. Remove the || true and
0.0.0/unknown fallbacks, and fail the Docker build immediately when either
command fails or produces an invalid/unclassified version; preserve normal
patching only for successfully parsed versions.

In `@scripts/extract-semver.sh`:
- Around line 7-9: The version extraction must target the OpenClaw version
instead of selecting the first unrelated semantic version. In
scripts/extract-semver.sh lines 7-9, restrict matching to the OpenClaw-labeled
output or otherwise make extraction target-aware; in
src/lib/verify-deployment.ts lines 210-213, pass "openclaw --version" to
parseVersionFromText.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 056219d6-b8f9-4eab-80f6-b677df01b272

📥 Commits

Reviewing files that changed from the base of the PR and between cf04a13 and 7d35077.

📒 Files selected for processing (5)

• Dockerfile
• scripts/extract-semver.sh
• src/lib/verify-deployment.test.ts
• src/lib/verify-deployment.ts
• test/openclaw-version-parser.test.ts

[HOYALIM]

Addressed Advisor blocker PRA-1 in e6bed8d: the install-block harness now stages and remaps the production OpenClaw version extractor. Exact provenance reuse is exercised with decorated output, and malformed output plus command failure are both proven to stop before npm pack/install. Validation: npm exec -- vitest run test/openclaw-integrity-pin-base.test.ts test/openclaw-integrity-pin-contract.test.ts test/openclaw-integrity-pin-plugin-install.test.ts test/openclaw-version-parser.test.ts src/lib/verify-deployment.test.ts (87 passed), npm run typecheck:cli, and npm run check:diff passed.

[wscurran]

✨ Thanks for the fix. Hardening the OpenClaw version parsing to fail closed on malformed output improves deployment reliability. Ready for maintainer review.

---

Related open issues:

• #5896 Post-tag hardening: close OpenClaw 2026.6.9 trust, live-proof, and compatibility-debt gaps

[prekshivyas]

Reviewed the version parsing and fail-closed Docker/runtime paths. The parser is deliberately label-aware, command failures are rejected, and the focused tests cover decorated, malformed, and failed output. No blocking findings.

[prekshivyas]

Re-reviewed the current head after syncing main. The parser is now included in optimized build-context staging and both Dockerfile harnesses execute the real helper; the formerly failing integration suites pass 45/45, with CLI build/typecheck and hooks green.

[prekshivyas]

Re-reviewed at d7d8da5: the TypeScript deployment verifier now mirrors the strict OpenClaw-labelled-or-bare semver grammar, including rejection of unrelated plugin versions. Focused verification tests and CLI build/typecheck pass.

[prekshivyas]

@cv Exact-head E2E authorization is the only remaining gate for d7d8da570292e9ba637e467925cca99398ffaa45. Trusted selection chose cloud-onboard, but this is a fork PR, so no secrets were exposed and the credentialed job was intentionally not run. Please approve the approve-credentialed-e2e-skip-for-fork-pr deployment on controller run 29466438703 to record the skip. Normal CI, advisor (0/0/0), CodeRabbit, DCO, macOS, and WSL are green.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review is ineligible. To be eligible to request a review, you need a paid Copilot license, or your organization must enable Copilot code review.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.