perf(messaging): stabilize image plan cache identity

[apurvvkumaria]

Summary

The real five-channel Hermes stop/start lifecycle returns to a semantically identical all-active messaging plan, but compact persistence rebuilds its object insertion order and changes the lifecycle-only workflow value. Those cache-irrelevant differences changed NEMOCLAW_MESSAGING_PLAN_B64 and invalidated downstream image layers. Full host lifecycle serialization remains unchanged; only the hydrated image-build payload now omits workflow and canonicalizes object keys while preserving array order.

Related Issue

Part of #7144 and #7140.

This does not overlap the Hermes base repin in #7582 or managed BuildKit failure handling in #7586. The selected live Hermes E2E remains gated on refreshing this branch after #7582 lands.

Changes

• Keep encodePlan, decodePlan, environment persistence, and strict host-side lifecycle parsing unchanged.
• Add an image-build-only encoder that removes exactly the top-level workflow field and recursively canonicalizes object keys after native JSON normalization.
• Route only the staged Dockerfile messaging ARG through that build-specific encoder.
• Exercise the production built-in Hermes planner across Telegram, Discord, WeChat, Slack, and WhatsApp, with compact registry persistence at every stop/start transition.
• Prove the lifecycle plans are semantically equal after removing workflow, their raw JSON key order differs, their image identities now match, and reordered arrays still produce distinct identities.
• Lock that the Dockerfile payload omits workflow while retaining hydrated channel, render, and runtime fields.

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 — justification: this changes only internal Docker image cache identity; commands, flags, configuration, persistence, and channel lifecycle semantics remain unchanged.
• 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: independent exact-diff review confirmed the full lifecycle boundary is unchanged, the build parser already treats workflow as optional, runtime consumers do not read it, arrays remain ordered, and all nine security categories pass.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: internal image-cache identity only; no user-visible command, configuration, persisted state, or stop/start behavior changed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed
• Targeted behavior tests pass for the current change set — 54/54 focused CLI tests and 45/45 messaging build/image-boundary integration tests passed.
• Applicable broad gate passed — npm run checks, CLI type-check, Biome, source-shape, test-title, project-membership, and test-size checks passed.
• 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)

Selected live E2E will be rerun at the refreshed exact head after #7582 lands; the prior Hermes run failed during stale-base onboarding before this cache behavior executed.

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved consistency when preparing messaging plans for Docker image builds.
  • Ensured equivalent plans produce stable encoded output, even when object property ordering differs.
  • Prevented workflow-specific data from being included in image-build configuration.
  • Preserved messaging image configuration across Hermes stop/start lifecycle operations.
  • Added validation to confirm generated build plans contain the expected metadata and remain reusable.

[coderabbitai]

📝 Walkthrough

Walkthrough

Image-build messaging plans now use canonical JSON serialization with sorted object keys and omit workflow before base64 encoding. Dockerfile patching uses this encoding, with lifecycle tests validating payload stability, channel-order sensitivity, and workflow omission.

Changes

Canonical plan encoding

Layer / File(s)	Summary
Canonical JSON serialization src/lib/messaging/applier/setup-applier.ts, src/lib/onboard/dockerfile-patch.ts	Plan image-build payloads are canonicalized before base64 encoding, and Dockerfile messaging arguments use the image-build encoder.
Encoding behavior validation src/lib/messaging/applier/setup-applier.test.ts, src/lib/onboard/dockerfile-patch.test.ts	Lifecycle tests verify stable image-build payloads, channel-order sensitivity, expected metadata, and omission of workflow.

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

Possibly related PRs

• NVIDIA/NemoClaw#7580: Both changes cover Hermes channel stop/start lifecycle handling and persisted messaging plans.

Suggested labels: integration: hermes, area: performance, platform: container

Suggested reviewers: cv, sandl99

🚥 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
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: stabilizing image-build messaging plan cache identity.

✨ 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 codex/7144-canonical-messaging-plan

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit b6fd694 in the codex/7144-canonical... branch remains at 96%, unchanged from commit f7d2531 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit b6fd694 in the codex/7144-canonical... branch is 81%. The coverage in commit f7d2531 in the main branch is 80%.

Show a code coverage summary of the most impacted files.

File	main f7d2531	codex/7144-canonical... b6fd694	+/-
src/lib/onboard...box-prebuild.ts	92%	73%	-19%
src/lib/actions...ocker-health.ts	82%	65%	-17%
src/lib/actions...confirmation.ts	79%	69%	-10%
src/lib/state/m...-acquisition.ts	89%	84%	-5%
src/lib/actions...e-validation.ts	81%	84%	+3%
src/lib/shields/index.ts	67%	72%	+5%
src/lib/actions...lution-probe.ts	88%	93%	+5%
src/lib/actions...x/mcp-bridge.ts	36%	43%	+7%
src/lib/actions...-add-restart.ts	10%	19%	+9%
src/lib/onboard/docker-cdi.ts	70%	80%	+10%

---

_{Updated July 26, 2026 20:50 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 2 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 2 more warnings, 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: channels-add-remove, channels-stop-start, onboard-repair, onboard-resume, cloud-onboard

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: 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 `@src/lib/messaging/applier/setup-applier-encoding.test.ts`:
- Around line 55-67: Rewrite reverseObjectKeys without introducing if
statements, using an approved existing helper if available or an
expression-based transformation that preserves recursive array handling,
primitive/null passthrough, and reversed object-key order. Keep the fixture
behavior unchanged while removing the branching reported by the guardrail.

🪄 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: 8bd8b739-e639-4cdb-b85c-504aba0eb1df

📥 Commits

Reviewing files that changed from the base of the PR and between d4a859a and af4b733.

📒 Files selected for processing (2)

• src/lib/messaging/applier/setup-applier-encoding.test.ts
• src/lib/messaging/applier/setup-applier.ts

[apurvvkumaria]

Exact-head E2E diagnosis

Selected E2E run: https://github.com/NVIDIA/NemoClaw/actions/runs/30203756186

• channels-add-remove passed on its first runner in 9m07s.
• channels-stop-start (openclaw) passed on its first runner in 16m11s.
• channels-stop-start (hermes) completed normally in 3m06s; cleanup and artifact upload both passed. This was not a runner cancellation.
• Hermes failed during its initial onboarding build, before this PR's plan-canonicalization behavior could be exercised.

The uploaded artifact shows the known prerequisite chain:

1. The pinned fa052… Hermes base contains npm 11.13.0, while the Dockerfile's reviewed patch contract requires npm 11.18.0.
2. Local BuildKit therefore fails closed on the npm identity check.
3. Current main masks that root cause by trying the classic gateway builder, which then fails on the first required RUN --mount.

#7582 changes only the stale base pin to reviewed digest c925…; #7586 preserves the original BuildKit evidence instead of attempting the incompatible fallback. #7589 changes neither the Dockerfile nor builder selection.

I will not rerun this stale head or duplicate either prerequisite. After #7582 lands, refresh #7589 from main and run the same selected E2E once at the new exact head.

[cv]

The serialization change is security-safe, but the PR does not yet prove the claimed production cache reuse. On the real lifecycle, onboarding emits workflow=onboard and restart emits workflow=rebuild, so their canonical payloads still differ; rebuild-to-rebuild is already byte-identical with the prior encoder. Please add a production-path regression that demonstrates an actual insertion-order cache miss fixed by this change, or use a build-specific identity that excludes only proven cache-irrelevant metadata while preserving runtime-plan decoding. After #7582 lands, refresh and require the selected Hermes/OpenClaw E2E set to pass. The current Hermes failure occurs during onboarding because of the stale base/BuildKit prerequisite and is not caused by this patch.

[apurvvkumaria]

Exact-head gate diagnosis for 1c2370002:

• Ordinary CI passed (37 checks).
• The two red statuses are the controller check and its observer for the same event.
• Controller run 30210723677 received HTTP 500 from GitHub while creating the e2e.yaml workflow dispatch.
• No child E2E run was created, so no product assertion ran and no hosted runner was lost.

I am not blindly rerunning the ambiguous POST. The systemic recovery is tracked in #7593, including correlation-based read-only reconciliation and exact child-run authorization.

For this PR, the safe next step is still to merge #7582, refresh this branch from current main, and let the new exact head/base identity run the selected E2E plan. The current code review feedback is addressed and there are no unresolved review threads.