fix(onboard): exclude inactive Hermes messaging presets

[rsliter]

Summary

Hermes post-boot policy selection could retain repository-owned messaging presets when enabledChannels did not include those channels. The selector now removes those inactive presets, preserves same-name custom presets, and retains required presets for enabled channels without changing OpenClaw selection.

Related Issue

Part of #10153.

Supersedes #10296. This PR preserves Charan Jagwani's protocol-aware Hermes Discord fixture correction as commit 3cf9274893309fa837c994ae15680ce9849ae185 and adds the production inactive-preset correction.

E2E Root-Cause Claim

E2E root cause: Hermes policy selection / post-boot preset reconciliation / an inactive repository-owned messaging preset survives the authoritative enabled-channel set and references an unattached provider.

Source run: https://github.com/NVIDIA/NemoClaw/actions/runs/32869481833

Affected jobs:

• Hermes open egress, job 97873593428
• Hermes Discord rebuild, job 97873593660

Stable signature: credential_binding references provider '<sandbox>-slack-app', but that provider is not attached to the sandbox.

Scope: one root cause across two jobs. PR #10271 separately owns the earlier equal-specificity Slack route ambiguity. The Hermes Slack API HTTP 500 result is not part of this PR.

Focused E2E selectors: common-egress-agent-hermes-open-reference,hermes-discord.

Changes

• Derive repository-owned messaging preset names from the channel manifest registry.
• Exclude inactive Hermes messaging presets from fresh suggestions, recorded resume state, applied-preset preservation, and custom-list reconciliation.
• Preserve same-name custom presets and existing OpenClaw behavior.
• Merge required presets for enabled Hermes messaging channels after pruning inactive presets.
• Persist the selected preset list only after gateway synchronization and post-sync readiness succeed, so failed removal remains retryable.
• Add regression coverage for empty enabled channels, Discord-only and Google Chat selection, stale applied Slack state, custom ownership, failed removal and resume, custom lists, and OpenClaw compatibility.

The shared pruner serves the fresh, resume, and custom selection consumers. Separate filters at each call site would duplicate the channel-to-preset authority. The focused suggestion, resume, selection, and handler tests protect these paths.

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:
• 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: Codex Desktop independently reviewed all nine security categories at commit under review f53c448bdb2bc04a99c7ef7059821cec886a4eda; result PASS with no findings. The latest commit is a signed empty child of 39aaae46641a133818622f441d63410905b4f574 with the identical reviewed tree. The selector narrows repository-owned Hermes messaging presets to enabled channels, preserves same-name custom policies, restores required presets after pruning, and persists the selection only after live synchronization and readiness succeed. The change does not expose credentials or widen hosts, providers, methods, protocols, or policy authority.
• Non-success, skipped, or missing CI check accepted by maintainer. Check name, approval link, and follow-up issue: None accepted. Current exact-head checks are still in progress.

DGX Station Hardware Evidence

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

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• npm run validate:pr passed for the unchanged effective patch at 0273a1deb451f2c106658c27d7d0482eb9f913f9. Commit under review f53c448bdb2bc04a99c7ef7059821cec886a4eda is a signed empty child with the identical tree, based on current main 803a587752aef1896c659f0ed7373d501b3b4b24.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above. For the unchanged effective patch, 177 focused deterministic tests and the added rebuild regression passed 1/1. The CLI build and typecheck, repository checks, npm run validate:pr, npm run docs with 0 errors and 2 existing warnings, and git diff --check passed. The current signed empty child has the identical tree and stable patch ID.
• Applicable broad gate passed. Not run because this change affects one policy-selection failure class; the focused suite and npm run validate:pr 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)

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Reviewed the complete 24-file effective diff at commit under review f53c448bdb2bc04a99c7ef7059821cec886a4eda against base SHA 803a587752aef1896c659f0ed7373d501b3b4b24. The latest PR commit is a signed empty child of 39aaae46641a133818622f441d63410905b4f574 with the same tree, and the stable patch ID matches the previously corrected diff. The four changed documentation pages accurately limit inactive built-in messaging preset removal and exact custom-policy preservation to Hermes. Shared onboarding guidance accurately states that skip mode applies required presets for enabled channels. The diagnostic, comments, and behavior-oriented test titles match the implementation. The supplied CLI build and typecheck, repository checks, npm run validate:pr, docs build with 0 errors and 2 existing warnings, focused deterministic tests, rebuild regression, and fresh git diff --check passed.
• Agent: Codex documentation writer subagent (/root/docs_review_10270)

---

Signed-off-by: Rebecca Sliter 571084+rsliter@users.noreply.github.com

Summary by CodeRabbit

• Bug Fixes
  • Improved Hermes onboarding and sandbox rebuilds by removing inactive built-in messaging presets.
  • Preserves enabled-channel and custom presets, including custom presets sharing names with inactive channels.
  • Added Google Chat support to channel-based preset selection.
  • Improved interrupted onboarding recovery, persistence failures, and retry behavior.
  • Preserves required presets in custom and skip modes for enabled messaging channels.
• Documentation
  • Clarified messaging-channel behavior during onboarding and sandbox recovery.
• Tests
  • Expanded coverage for onboarding, rebuilds, resume selection, custom ownership, retries, and supported channels.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[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

Hermes onboarding now removes inactive repository messaging presets while preserving custom presets. Policy persistence failures now stop completion. Selection callbacks wait for sandbox readiness and synchronization. Rebuilds filter inactive presets. Discord endpoint binding now requires an exact protocol match.

Changes

Hermes messaging preset pruning

Layer / File(s)	Summary
Preset pruning helper src/lib/onboard/messaging-policy-presets.ts, src/lib/onboard/messaging-policy-presets.test.ts	Adds Hermes-only filtering for inactive repository messaging presets. Custom presets and non-Hermes selections remain preserved.
Selection and reconciliation integration src/lib/onboard/policy-selection.ts, src/lib/onboard/policy-preset-reconciliation.ts, src/lib/onboard/openclaw-otel-policy-presets.test.ts	Applies shared pruning to suggestions and unavailable-preset reconciliation. Passes enabled channels and custom preset names through the flows.
Selection callback ordering src/lib/onboard/policy-selection.ts, src/lib/onboard/policy-selection-recorded-tier.test.ts	Moves selection callbacks after sandbox readiness checks and policy synchronization.
Policy persistence failure handling src/lib/onboard/machine/handlers/policies.ts, src/lib/onboard/policy-preset-persistence.ts, src/lib/onboard/machine/handlers/*.test.ts	Returns persistence results and throws when finalized policy persistence fails. Tests cover retry behavior and failed Hermes cleanup.
Rebuild policy filtering src/lib/actions/sandbox/rebuild-backup-phase.ts, src/lib/actions/sandbox/rebuild-backup-phase.test.ts, docs/manage-sandboxes/*.mdx	Removes inactive built-in Hermes messaging presets during rebuilds while preserving custom policies and backup state.
Hermes behavior validation src/lib/onboard/policy-resume-selection.test.ts, test/onboarding/*.test.ts, docs/reference/*.mdx	Covers inactive preset removal, enabled preset retention, custom ownership, Google Chat, skip mode, resume reconciliation, and OpenClaw behavior.

Hermes Discord protocol binding

Layer / File(s)	Summary
Protocol-specific endpoint binding test/e2e/fixtures/hermes-discord-policy-binding.ts, test/e2e/live/hermes-discord.test.ts, test/e2e/support/hermes-discord-policy-binding.test.ts	Requires a protocol for binding, enforces exact protocol matching, and updates websocket fixtures and regression coverage.

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

Merge Risk: ⚪ Minimal · up to a15a8

The PR’s inactive-preset behavior is covered by focused tests and no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant PolicySelection
  participant SandboxControlPlane
  participant PolicySynchronization
  participant SelectionCallback
  PolicySelection->>SandboxControlPlane: check readiness
  SandboxControlPlane-->>PolicySelection: readiness result
  PolicySelection->>PolicySynchronization: synchronize policies
  PolicySynchronization-->>PolicySelection: synchronization result
  PolicySelection->>SelectionCallback: report selection after success

Loading

Suggested reviewers: apurvvkumaria, aasthajh

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.76% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 20 files. (4 skipped:…	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 and concisely describes the primary change: excluding inactive Hermes messaging presets during onboarding.

Full details: Docstring Coverage

Explanation

Docstring coverage is 11.76% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 20 files. (4 skipped: 4 unsupported.)

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-hermes-inactive-messaging-presets

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit 14be190 in the codex/fix-hermes-ina... branch remains at 96%, unchanged from commit b4acfb6 in the main branch.

---

_{Updated August 27, 2026 02:56 UTC}

[rsliter]

Current head c1f19da has one candidate-owned CI blocker that the advisor did not report.\n\ncli-test-shards (7) fails in src/lib/onboard/openclaw-otel-policy-presets.test.ts at line 78 because its messaging-policy-presets mock does not export the new pruneInactiveHermesMessagingPolicyPresets function called by policy-preset-reconciliation.ts at line 52. Update that mock, preferably by retaining the real module exports and overriding only the test dependency, then run the focused test before pushing.\n\nThe shard 3 setup-nim-flow-serving-profile.test.ts timeout appears unrelated to this diff. After the mock fix, let ordinary CI rerun and complete the required common-egress-agent-hermes-open-reference,hermes-discord focused E2E before moving this draft toward approval.

[cv]

I found no blocking correctness, product-scope, or security issue at commit e85bb2e. The manifest-derived Hermes pruning preserves operator-owned presets and OpenClaw behavior, and focused tests cover the changed paths. I am deferring approval because checks for the latest PR commit are still running. The available Review Advisor result applies to an earlier commit.

[rsliter]

Current head e85bb2e2481a220046913454b5a270e4c5137bcc is not ready for approval.

• The current PR Review Advisor blocker is valid: the changed Hermes preset matrices claim registry-wide coverage but omit the built-in googlechat preset. Add enabled and inactive Google Chat cases while preserving the custom-preset exception.
• The focused E2E run 32884667516 was correctly bound to candidate c1f19daa90b0b44bf979d55fb98806c46f1838f0. common-egress-agent-hermes-open-reference passed, but hermes-discord failed in exercise native Discord gateway rewrite; the proof emitted ERROR ReconnectWebSocket: None and never reached the rewrite assertions. The changes since that candidate add unit-test coverage and merge main but do not supply a passing replacement run. After the Google Chat fix, rerun common-egress-agent-hermes-open-reference,hermes-discord for the latest commit.
• The security and documentation receipts in the PR body still name c1f19daa9; refresh them against the final commit.

I will re-review the corrected exact head and approve once the blocker, receipts, ordinary checks, and focused E2E evidence are complete.

[rsliter]

Blocking review finding on exact head 0aa4b831c651c6f5d8964a7ed9194ce9015d14a1 against base d910fde70f0a4eece7adc8c752d8a2d3c831bc3d.

The Google Chat matrix commit addresses the earlier coverage blocker. One blocking correctness and security defect remains, matching Advisor PRA-1.

setupPoliciesWithSelection invokes onSelection before the pre-sync readiness check, syncPresetSelection, and the post-sync readiness check in all four reconciliation paths. The policies handler immediately marks the selection as reflecting the live set and writes the narrower list into the session. If removal of an inactive Hermes messaging preset fails, the session already omits that preset while the gateway still applies it. A later resume can accept the recorded list as a subset of the live list and skip reconciliation, leaving inactive channel egress applied.

Move each onSelection call until after gateway synchronization and the post-sync readiness check succeed. Keep the prior session selection when either step fails. Add a handler-level failure-and-resume regression that makes removal fail, proves the old selection remains recorded, and proves the next resume removes the inactive preset.

I am not treating PRA-2 as a blocking correctness or security finding. The same-name assertion may be more restrictive than the registry implementation, but it does not create a current behavior defect.

Security review: FAIL for Configuration and Security Headers because failed policy removal can persist session state that understates live egress. The other eight security categories pass for this head. The documentation receipt still names c1f19daa9; refresh it at the corrected final commit. After the fix, rerun common-egress-agent-hermes-open-reference,hermes-discord for the exact head because the prior Hermes Discord run failed before its rewrite assertions.

[rsliter]

Exact-head review classification for fcec4f32f2a29d876539e1a49a301441e4c77aad.

The prior session-persistence ordering defect is fixed. onSelection now runs only after gateway synchronization and post-sync readiness succeed, and the new regression proves a failed removal leaves the prior session selection retryable. I found no blocking correctness or security defect in the 10-file diff.

Advisor PRA-1 is non-blocking. NEMOCLAW_POLICY_MODE=skip intentionally skips policy additions; the public contract says it leaves a new preset inactive and an existing live set unchanged except for removing a disabled channel preset. Adding Discord in that branch would contradict skip mode.

Advisor PRA-2 identifies a valid pre-existing registry-persistence gap, but persistFinalizedPolicyPresets and registry.updateSandbox are unchanged by this PR. The candidate-owned failure was the early session update before live synchronization, and this commit corrects that boundary.

Security review: PASS in all nine categories. The change only narrows repository-owned Hermes messaging policy selection, preserves same-name custom ownership and OpenClaw behavior, adds no authority, exposes no credential, and fails before recording the narrower session state when synchronization or readiness fails. Focused regression coverage includes inactive Slack and Google Chat, enabled-channel preservation, custom ownership, resume, and synchronization failure.

This is not an approval. The recovery run for CLI shard 7 and the current managed-image check are still in progress, and the required exact-commit focused common-egress-agent-hermes-open-reference,hermes-discord evidence is still missing.

[ericksoa]

Exact-commit focused E2E classification for fcec4f32f2a29d876539e1a49a301441e4c77aad:

• Run 32892713331, attempt 3 used base d910fde70f0a4eece7adc8c752d8a2d3c831bc3d and trusted workflow 636f18ad1190823cffcc233e3d8c8e3bd04828b2.
• common-egress-agent-hermes-open-reference passed.
• hermes-discord passed provider health, configuration, and placeholder phases. It then failed the native gateway rewrite assertion with ERROR ReconnectWebSocket: None instead of UPGRADE.
• The failure matches open issue #9773, which records the same post-OpenShell-0.0.106 phase-5 signature and owns the Discord provider-binding correction.

All ordinary PR checks are green after the shard-7 recovery. No approval was submitted.

[rsliter]

Exact-head Advisor reconciliation for f53c448bdb2bc04a99c7ef7059821cec886a4eda:

The Test Design finding is valid for one candidate-owned hunk. test/onboarding/onboard-policy-suggestions.test.ts expands the pre-existing self-derived suggestion and finalization paths contribute identical channel presets oracle by adding googlechat. That oracle derives its expected value from the same registry used by both paths, so the added row cannot independently catch a bad Google Chat mapping. The direct mapping tests, literal suggestion assertions, and onboard-preset-diff Google Chat cases already protect the behavior.

Make the smallest scoped correction: revert only the candidate addition of googlechat to that pre-existing cross-verification matrix. Keep the literal Google Chat suggestion and application regressions. Run the focused file and refresh exact-head receipts after the new commit.

The Design and Architecture import-coupling finding is not candidate-owned. Current main already imports isStaleBuiltinWebSearchPolicyPreset from policy-selection in rebuild-backup-phase.ts; this PR does not change that import. It does not block this fix.

Security review remains PASS across all nine categories. This is review feedback, not an approval.

[rsliter]

Reviewed exact head f53c448bdb2bc04a99c7ef7059821cec886a4eda and the current PR Review Advisor reports.

Two changes are required before approval:

1. src/lib/actions/sandbox/rebuild-backup-phase.ts imports isStaleBuiltinWebSearchPolicyPreset through policy-selection.ts, even though that module only re-exports the pure predicate from policy-preset-reconciliation.ts. This makes rebuild depend on the interactive onboarding orchestration module and its prompt, mutation, tracing, and session dependencies. Import the predicate directly from ../../onboard/policy-preset-reconciliation. Existing rebuild coverage is sufficient for this import-boundary correction.

2. test/onboarding/onboard-policy-suggestions.test.ts derives its expected channel presets from allMessagingChannelPolicyPresets, then compares two paths that both use that same mapping. A wrong registry mapping can therefore change the implementation and oracle together. Remove this cross-verification test, or replace the suggestion half with literal expected presets. The direct mapping tests and finalization matrix already own the other boundaries.

I found no behavior, trust, operations, dependency-use, migration, or documentation defect in the current effective patch. Exact focused common-egress-agent-hermes-open-reference,hermes-discord E2E is still required after the final commit.

[github-actions]

PR review advisory complete for commit 14be190: read the full review. Read it before deciding whether to request changes, approve, or merge this PR.

All previous runs

[cjagwani]

Both required focused branch E2Es passed on latest PR commit 14be190.

common-egress-agent-hermes-open-reference: https://github.com/NVIDIA/NemoClaw/actions/runs/33038874545/job/98408045584

hermes-discord: https://github.com/NVIDIA/NemoClaw/actions/runs/33038874545/job/98408045727

Full exact run: https://github.com/NVIDIA/NemoClaw/actions/runs/33038874545

[sandl99]

Requested Hermes E2E targets pass on commit 14be190.