feat(runtime): package commit-matched companion plugins

[hannesrudolph]

Related: #60

Additional instructions

MUST: Keep Allow edits from maintainers enabled for this PR so maintainers
can help update the branch when needed.

What Problem This Solves

runtime build-local can preserve bundled source extensions, but it cannot produce a complete release-shaped runtime when an official plugin is published separately from the OpenClaw package. Operators building an exact source runtime for plugins such as Codex, iMessage, or WhatsApp must otherwise assemble and verify those companion trees outside OCM.

Current OpenClaw source graphs can also contain nested private workspace:* dependencies. The existing adapter supplies direct workspace packages, but nested packed archives can retain unresolved workspace protocols and fail during isolated installation.

Why This Change Was Made

Add repeatable --companion <plugin-id> selection to the existing local runtime builder. Each selected companion must use OpenClaw's package-local release contract, match the host version, be publishable, and remain separate from already bundled extensions. OCM installs each companion in a runtime-owned tree and records its package identity, artifact digest, entrypoint, entrypoint digest, and completed package-tree integrity.

Resolve the complete private workspace dependency closure and rewrite nested workspace:* protocols only inside scratch package archives. The source checkout remains unchanged. Existing --for-env, --include-source-extensions, build-profile selection, and full-tree verification remain authoritative and are not replaced.

Gateway lifecycle and named Tailscale Service ingress changes are intentionally outside this PR.

User Impact

Operators can build one reproducible, release-shaped runtime from an OpenClaw checkout together with explicitly selected commit-matched companion plugins. Incomplete, mismatched, duplicate, non-publishable, or drifted companion trees fail closed during build or verification instead of surfacing later as runtime plugin failures.

Existing local builds that do not select companions retain their current behavior.

Evidence

• Isolated split branch based directly on current main; it contains no gateway lifecycle or Tailscale ingress changes.
• cargo fmt --all -- --check: passed.
• git diff --check origin/main..HEAD: passed.
• cargo test --locked --test runtime_command_tests --test store_compatibility_tests: 58 passed, 0 failed.
• Hosted CI passed on macOS, Ubuntu, Windows, formatting, and the Rust 1.88 minimum lane.
• The split conflict was limited to CHANGELOG.md; current upstream release entries were retained and only the runtime packaging note was added.
• No OCM binary was installed locally, and no resident daemon or managed gateway was restarted.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 21, 2026, 4:16 PM ET / 20:16 UTC.

ClawSweeper review

What this changes

This PR adds repeatable runtime build-local --companion <plugin-id> packaging for separately published OpenClaw plugins, plus workspace archive rewriting and runtime integrity metadata.

Merge readiness

⚠️ Ready for maintainer review - 3 items remain

Keep open for maintainer product direction: the two prior compatibility findings are fixed on the current head, but the new public companion-packaging contract needs explicit sponsorship before merge.

Priority: P2
Reviewed head: d2c86c05ee1ef2b2f1a5cf163f0193f1ac809925
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The repaired implementation and focused coverage are solid, with merge readiness now depending on product sponsorship rather than a patch defect.
Proof confidence	🌊 off-meta tidepool	Not applicable: This MEMBER-authored PR is not subject to the external-contributor real-behavior-proof gate; its focused fixtures and CI remain supplemental evidence.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This MEMBER-authored PR is not subject to the external-contributor real-behavior-proof gate; its focused fixtures and CI remain supplemental evidence.
Evidence reviewed	6 items	Current main does not provide the new mode: The PR diff adds all --companion parsing and wiring; the current default-branch implementation has only the existing build-local options. Manifest-ID fix is present: Companion lookup now uses the shared source-plugin manifest inventory and retains the physical directory separately for package tooling. Staged-host peer fix is present: Companion installs omit peers and replace a declared OpenClaw peer with the staged host after dependency copying.
Findings	None	None.
Security	None	None.

Live Verification

Command: ./bin/ocm help runtime build-local

Result: FAIL (failed) — execution before step 1 run: sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.22.0.tgz

sh -lc pnpm install --ignore-scripts --frozen-lockfile failed: ! Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-11.22.0.tgz

Assertions:

• FAIL expect_output: --companion ‹plugin-id›

How this fits together

OCM’s local runtime builder packages an OpenClaw checkout into a release-shaped managed runtime. This change optionally packages selected official companion plugins beside the staged host package and records metadata for runtime verification.

flowchart LR
A[OpenClaw checkout] --> B[Local runtime build]
B --> C[Select plugin by manifest ID]
C --> D[Package plugin and dependencies]
D --> E[Stage beside host package]
E --> F[Record hashes and metadata]
F --> G[Runtime verification]

Loading

Decision needed

Question	Recommendation
Should OCM permanently support runtime build-local --companion <plugin-id> for separately published OpenClaw plugins?	Keep runtime builds core-only: Do not add this public mode unless an owner explicitly sponsors the ongoing packaging contract.

Why: The implementation can be assessed technically, but accepting a new public CLI mode and its compatibility commitment requires maintainer intent.

Before merge

• Resolve merge risk (P1) - Merging creates a compatibility-sensitive, operator-facing companion-plugin packaging contract that OCM would need to support across OpenClaw release tooling changes.
• Complete next step (P2) - The remaining blocker is maintainer sponsorship of a new public runtime packaging contract, not a narrow repair task.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus test growth	production +1,092/-23; tests +367/-3	The feature substantially expands runtime packaging and is accompanied by focused regression coverage.
Files affected	15 files changed	The change spans CLI, packaging, metadata, verification, documentation, and tests.

Merge-risk options

Maintainer options:

1. Sponsor the contract
   Merge only after an owner explicitly accepts the new CLI and plugin-release compatibility boundary.
2. Keep the current runtime scope
   Pause or close this feature path if OCM should not own separate companion-plugin packaging.

Technical review

Best possible solution:

Either explicitly sponsor and document the companion packaging contract as supported OCM behavior, or keep local runtime builds limited to the existing core and source-extension paths.

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

Not applicable: this PR proposes a new runtime-build capability rather than reporting a broken existing behavior; focused fixtures cover the repaired code paths.

Is this the best way to solve the issue?

Unclear: the two prior technical defects are repaired, but only maintainers can decide whether this new public packaging contract is the right product direction.

AGENTS.md: not found in the target repository.

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

Labels

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This MEMBER-authored PR is not subject to the external-contributor real-behavior-proof gate; its focused fixtures and CI remain supplemental evidence.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

• P2: This is a bounded runtime-packaging feature requiring normal-priority product review.
• merge-risk: 🚨 compatibility: The new public CLI mode and plugin layout establish an ongoing operator and release-tooling compatibility contract.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This MEMBER-authored PR is not subject to the external-contributor real-behavior-proof gate; its focused fixtures and CI remain supplemental evidence.

Evidence

What I checked:

• Current main does not provide the new mode: The PR diff adds all --companion parsing and wiring; the current default-branch implementation has only the existing build-local options. (src/cli/runtime.rs:304, 768714ae3491)
• Manifest-ID fix is present: Companion lookup now uses the shared source-plugin manifest inventory and retains the physical directory separately for package tooling. (src/store/runtimes.rs:1084, d2c86c05ee1e)
• Staged-host peer fix is present: Companion installs omit peers and replace a declared OpenClaw peer with the staged host after dependency copying. (src/store/runtimes.rs:1359, d2c86c05ee1e)
• Focused regression coverage: The fixture uses a manifest ID distinct from its directory and verifies a simulated registry peer is replaced by the staged host. (tests/runtime_command_tests.rs:1412, d2c86c05ee1e)
• Runtime ownership history: Current-main history identifies the original local-runtime implementation and the later source-extension packaging work that this feature extends. (src/store/runtimes.rs:2471, 5b806af7b185)
• Product decision remains explicit: The follow-up states that long-term ownership of the public companion contract was intentionally left for maintainer sponsorship. (d2c86c05ee1e)

Likely related people:

• Shakker: Introduced the local OpenClaw package-runtime path and has extensive subsequent runtime-store history. (role: original local-runtime feature author; confidence: high; commits: 5b806af7b185, 7e110ae25c82; files: src/store/runtimes.rs, src/runtime/registry.rs)
• Jason (Json): Added source-extension preservation and current OpenClaw build-local support, which the companion flow reuses. (role: recent adjacent runtime contributor; confidence: high; commits: 614f6cb4b9c4, c34c7072bf28; files: src/store/runtimes.rs, tests/runtime_command_tests.rs)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (2 earlier review cycles)

• reviewed 2026-08-21T19:11:49.269Z sha b02a8f7 :: found issues before merge. :: [P1] Link declared OpenClaw peers to the staged host | [P2] Resolve companions by manifest ID, not source directory
• reviewed 2026-08-21T19:21:20.202Z sha b02a8f7 :: needs changes before merge. :: [P1] Link companion OpenClaw peers to the staged host | [P2] Resolve companion selections by manifest ID

[hannesrudolph]

@clawsweeper re-review

I accepted both actionable compatibility findings and pushed d2c86c0.

Manifest-ID selection

--companion now resolves the requested plugin ID through the existing source-plugin manifest inventory. LocalCompanionSpec retains the physical source directory separately, so a plugin such as manifest ID codex in extensions/codex-published is selected as --companion codex while OpenClaw's package-local build scripts still receive the real directory.

This reuses the same ambiguity and package validation boundary as source-extension selection instead of creating a second manifest scanner.

Staged host peer

Companion installation now uses --omit=peer to avoid resolving a registry OpenClaw host during isolated npm installation. After runtime dependencies are copied, the shared extension peer helper replaces any nested openclaw peer with a link or copy of the staged host package. This is defense in depth: even an installer that leaves a nested peer cannot shadow the commit-matched runtime.

Regression coverage

The companion fixture now:

• stores source under extensions/codex-published with manifest ID codex;
• declares an openclaw peer;
• simulates npm leaving a bogus 9999.0.0 registry peer; and
• proves the packaged companion resolves the staged 2026.8.1 host and contains no registry-peer marker.

Validation:

• 14/14 runtime_build_local tests passed.
• 4/4 store compatibility tests passed.
• Full 54-test runtime command suite passed with --test-threads=1.
• The pre-existing concurrent-download timing test timed out twice only in the locally parallel full run, then passed in isolation and in the complete serial run; hosted CI is the authoritative parallel check.
• Formatting and git diff --check passed.

Product-contract decision

I did not attempt to resolve the sponsorship question in code. This PR continues to propose --companion as an intentional public OCM contract backed by OpenClaw's package-local release tooling. Whether OCM should own that contract long-term remains a maintainer product decision, now separated from the two repaired correctness defects.

No local OCM deployment or gateway restart was performed.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

[hannesrudolph]

Maintainer decision: sponsor this contract.

We are intentionally accepting runtime build-local --companion <plugin-id> as a supported OCM operator surface, including the compatibility boundary with OpenClaw's package-local companion release tooling. The repaired manifest-ID and staged-host peer behavior, hosted CI, focused tests, and the combined live OCM smoke provide sufficient evidence to merge.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: feat(runtime): package commit-matched companion plugins This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.