feature(version): normalize version markers for different build types

[ndizazzo]

Summary

This PR separates mesh-llm's release identity from its build/display identity.

Local/source builds now stamp and report SHA-bearing versions like 0.68.0+gABCDEF.dirty across user-visible surfaces, while release/compatibility paths continue to use the plain Cargo package version. This lets source builds accurately identify what code is running without breaking update checks, mesh/runtime compatibility, native-runtime cache layout, or release packaging.

Net effect for release builds

Release builds continue to behave as plain release versions:

• RELEASE_VERSION remains the Cargo package version.
• crate::VERSION remains mapped to release identity for compatibility-sensitive paths.
• Native runtime cache keys continue to use release/manifest mesh_version, not SHA-bearing build versions.
• Release native-runtime manifests still default to:
  releases/download/v<release>/native-runtimes.json
• Publish/release ordering now includes the new mesh-llm-build-info crate.

Net effect for local/source builds

Local builds now get a derived build version when MESH_LLM_BUILD_VERSION is not preset:

<release>+g<6-char-uppercase-sha>[.dirty]

That build version is now used by:

• mesh-llm --version
• /api/status.version
• update current-version inputs
• MCP server-info version
• runtime owner metadata
• benchmark prompt-import/user-agent metadata

A local SHA build will no longer be treated as older just because the latest public release is the same base version. SHA builds also default native-runtime manifest discovery to the latest release manifest, while still installing/loading runtimes under release/manifest cache keys.

On startup, mesh-llm now:

1. checks for an already installed compatible native runtime;
2. skips install/network work on cache hit;
3. makes exactly one install attempt on cache miss;
4. falls back cleanly without retry loops if install fails or no compatible artifact exists.

CI and release impact

No GitHub workflow YAML changes were needed, but repo scripts were updated so CI/release automation understands the new crate:

• scripts/affected-crates.sh includes mesh-llm-build-info.
• scripts/plan-clippy-batches.sh includes and weights the new crate.
• scripts/publish-crates.sh publishes mesh-llm-build-info before dependent crates.
• tools/xtask release-target checks now accept VERSION = RELEASE_VERSION.
• Repo-consistency checks pass for release targets and CI crate lists.

Validation

Passed validation included:

• cargo test -p mesh-llm-build-info --lib
• cargo test -p mesh-llm-system --lib
• cargo test -p mesh-llm-runtime-install --lib
• cargo test -p mesh-llm-native-runtime --lib
• cargo test -p mesh-llm-host-runtime --lib
• cargo check -p mesh-llm
• just build
• just release-build
• live smoke verifying derived/overridden build versions and /api/status.version
• repo consistency:
  • cargo run -p xtask -- repo-consistency release-targets
  • cargo run -p xtask -- repo-consistency ci-crate-lists

Summary by CodeRabbit

• New Features

  • CLI and API now report a stamped build version (can include git SHA) for development builds.

• Improvements

  • Update-checking and version comparisons now distinguish SHA-stamped builds from releases for more accurate results.
  • Runtime install and caching logic use build/release versioning to select manifests and cache entries.

• Documentation

  • CLI guide updated with a “Check the running version” section explaining reported version strings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1e75cae1-c41e-4ce6-8f98-9d143133ab52

📥 Commits

Reviewing files that changed from the base of the PR and between 2f6e33a and b65f1ad.

📒 Files selected for processing (2)

• crates/mesh-llm-host-runtime/src/system/native_runtime.rs
• website/src/docs/pages/CLI.md

✅ Files skipped from review due to trivial changes (1)

• website/src/docs/pages/CLI.md

🚧 Files skipped from review as they are similar to previous changes (1)

• crates/mesh-llm-host-runtime/src/system/native_runtime.rs

---

📝 Walkthrough

Walkthrough

This PR adds a new dependency-free crate, mesh-llm-build-info, that exposes BUILD_VERSION, RELEASE_VERSION, and is_sha_build(); it stamps builds via scripts, switches consumers to the stamped build version for display/agent/update checks, makes autoupdate and manifest resolution SHA-build aware, and refactors native runtime startup into plan resolution followed by library loading.

Changes

Build-time Versioning Infrastructure

Layer / File(s)	Summary
New mesh-llm-build-info crate foundation crates/mesh-llm-build-info/Cargo.toml, README.md, build.rs, src/lib.rs	Introduces BUILD_VERSION (MESH_LLM_BUILD_VERSION override or package version), RELEASE_VERSION (package version), is_sha_build() detection, a build script rerun directive, and unit tests.
Workspace registration and dependency wiring Cargo.toml, crates/*/Cargo.toml	Adds the new crate to workspace members and registers it as a workspace dependency for CLI, commands, host-runtime, runtime-install, and system crates.
Host-runtime constants and exports crates/mesh-llm-host-runtime/src/lib.rs	Exports BUILD_VERSION and RELEASE_VERSION from mesh_llm_build_info and makes VERSION an alias to RELEASE_VERSION.
API, CLI, plugin, runtime metadata updates crates/mesh-llm-cli/src/parser.rs, crates/mesh-llm-host-runtime/src/api/mod.rs, crates/mesh-llm-host-runtime/src/api/tests.rs, crates/mesh-llm-host-runtime/src/plugin/mcp.rs, crates/mesh-llm-host-runtime/src/runtime/mod.rs	Switches displayed/reporting version values to BUILD_VERSION, updates status payloads and tests, and updates owner metadata and MCP plugin version to use BUILD_VERSION.
Commands: benchmark and update integration crates/mesh-llm-commands/src/benchmark.rs, crates/mesh-llm-commands/src/update.rs	Uses BUILD_VERSION for benchmark user-agent and update current_version checks.
Build scripts stamping MESH_LLM_BUILD_VERSION scripts/build-linux.sh, scripts/build-mac.sh, scripts/build-release.sh, scripts/build-windows.ps1	Adds helpers to derive and export MESH_LLM_BUILD_VERSION (from preset or cargo/pkgid + git SHA + optional .dirty) and invokes them before cargo builds.
Manifest URL resolver and autoupdate SHA-awareness crates/mesh-llm-runtime-install/src/lib.rs, crates/mesh-llm-system/src/autoupdate.rs	Adds default_manifest_url(build_version,release_version), updates manifest_url usage, switches CURRENT_MESH_VERSION to RELEASE_VERSION, and updates version_newer to special-case SHA builds with tests and env guards.
Native runtime: plan-based startup loading crates/mesh-llm-host-runtime/src/system/native_runtime.rs	Refactors startup to resolve a NativeRuntimeStartupLoadPlan (CacheHit or PostInstall) before unsafe library loading; adds plan types, default install helpers, and expanded tests validating selection, cache identity, and install/load semantics.
Tooling, publish and CI script updates scripts/affected-crates.sh, scripts/plan-clippy-batches.sh, scripts/publish-crates.sh, tools/xtask/src/main.rs	Registers the new crate in workspace member lists, clippy weights, publish ordering, and version-extraction logic.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Suggested reviewers

• michaelneale
• i386

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 39.19% 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 accurately describes the main change: normalizing version markers to distinguish between release identity and build display identity across the codebase.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/version-checks-and-runtimes

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@crates/mesh-llm-host-runtime/src/system/native_runtime.rs`:
- Around line 210-217: The code currently treats a missing cache entry from
cache.find_installed(...) as a hard error via with_context(...)? which turns a
TOCTOU cache disappearance into an Err; instead return Ok(None) so the caller
(resolve_startup_native_runtime_plan_with / select_native_runtime) follows the
cache-miss one-shot install path. Modify the handling around
cache.find_installed(&cache_mesh_version, artifact.native_runtime_id()) so that
if the entry is not found (or the find returns a "missing" result), you convert
that case into Ok(None) rather than propagating an error; leave other unexpected
errors unchanged and still propagate them.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 32aed380-e6d8-4bae-a434-60b97035c43d

📥 Commits

Reviewing files that changed from the base of the PR and between cb3a818 and 2f6e33a.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (29)

• Cargo.toml
• crates/mesh-llm-build-info/Cargo.toml
• crates/mesh-llm-build-info/README.md
• crates/mesh-llm-build-info/build.rs
• crates/mesh-llm-build-info/src/lib.rs
• crates/mesh-llm-cli/Cargo.toml
• crates/mesh-llm-cli/src/parser.rs
• crates/mesh-llm-commands/Cargo.toml
• crates/mesh-llm-commands/src/benchmark.rs
• crates/mesh-llm-commands/src/update.rs
• crates/mesh-llm-host-runtime/Cargo.toml
• crates/mesh-llm-host-runtime/src/api/mod.rs
• crates/mesh-llm-host-runtime/src/api/tests.rs
• crates/mesh-llm-host-runtime/src/lib.rs
• crates/mesh-llm-host-runtime/src/plugin/mcp.rs
• crates/mesh-llm-host-runtime/src/runtime/mod.rs
• crates/mesh-llm-host-runtime/src/system/native_runtime.rs
• crates/mesh-llm-runtime-install/Cargo.toml
• crates/mesh-llm-runtime-install/src/lib.rs
• crates/mesh-llm-system/Cargo.toml
• crates/mesh-llm-system/src/autoupdate.rs
• scripts/affected-crates.sh
• scripts/build-linux.sh
• scripts/build-mac.sh
• scripts/build-release.sh
• scripts/build-windows.ps1
• scripts/plan-clippy-batches.sh
• scripts/publish-crates.sh
• tools/xtask/src/main.rs