test(hermes): cover MCP integrity through restart

[cjagwani]

Summary

Fix locked Hermes gateway restart after a managed MCP update. The root-owned restart controller now recognizes the guard-generated v1 MCP state record in the strict config hash while continuing to reject malformed, duplicate, unknown, or ambiguous records.

The PR also adds a focused live regression covering managed add, shields restoration, real gateway restart, integrity verification, and failed-reload rollback. It replaces #7743 on current main; repository rules forbid force-pushing the published replacement branch. One narrow test-only timeout adjustment salvages a workflow-boundary check that twice exhausted Vitest's default 5-second envelope despite its child process already being bounded to 30 seconds.

Related Issue

Closes #7499

Changes

• Parse zero or one exact nemoclaw-hermes-mcp-state-v1 metadata record in the locked Hermes strict hash, preserving legacy two-record hashes.
• Reject malformed, duplicate, or unknown metadata and duplicate config hash paths with GATEWAY_CONFIG_HASH_MISMATCH.
• Exercise the existing Hermes MCP live target through managed add, shields restoration, supervisor-mediated restart, exact locked file/hash verification, and public transaction inspection.
• Inject a first-reload failure and require the real rollback path to restore config and both anchors byte-for-byte, prove a healthy rollback reload, and confirm current state through the packaged public inspect flow.
• Scan raw Hermes files and the startup log after restart to confirm the fake bridge secret is absent.
• Give the existing workflow-boundary test a 40-second Vitest envelope around its already-bounded 30-second child process.

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 restores the existing documented locked Hermes restart contract; the v1 hash record is an internal guard-generated implementation detail.
• 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: Manual nine-category security review on 79767cd8c passed all categories. The root ownership/mode checks remain unchanged; parsing is bounded ASCII with an exact known-record regex, and negative tests cover malformed, duplicate, unknown, and ambiguous input.
• 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: The parser restores the existing locked Hermes restart contract while preserving fail-closed validation. The E2E follow-up only strengthens verification through public packaged behavior.
• Agent: Codex Desktop /root/replacement_docs_review

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, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — managed gateway control 4/4; Hermes MCP transaction 27/27; serial MCP live-selection E2E-support 41/41; workflow-boundary E2E-support 33/33; live Hermes target collection/import; semantic E2E phases 115 tests across 73 files; CLI typecheck; exact Vitest project-membership and test-size gates.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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: Charan Jagwani cjagwani@nvidia.com

Summary by CodeRabbit

• Tests
  • Expanded end-to-end coverage for managed MCP bridge setup, including Hermes shield restoration across a locked gateway restart.
  • Added rollback validation that confirms a failed managed reload restores Hermes configuration and integrity anchors.
  • Tightened Hermes-related secret expectations and updated Hermes phase sequencing.
  • Added unit coverage for strict locked-hash parsing, covering legacy/current Hermes state variants and rejecting malformed/ambiguous inputs.
  • Increased timeout for workflow-to-PR reporting integration E2E.
• Bug Fixes
  • Strengthened locked Hermes config-hash validation with strict state-line parsing and clearer mismatch handling.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds Hermes end-to-end coverage for shield restoration, gateway restart, locked configuration integrity, MCP registry state, rollback after an injected reload failure, strict hash parsing, and an explicit workflow test timeout.

Changes

Hermes MCP integrity lifecycle

Layer / File(s)	Summary
Locked Hermes hash validation scripts/managed-gateway-control.py, test/managed-gateway-control.test.ts	Parses Hermes state metadata from locked-hash input and rejects malformed, duplicate, or ambiguous records with GATEWAY_CONFIG_HASH_MISMATCH.
Restart and integrity validation test/e2e/live/mcp-bridge-hermes-lifecycle.ts, test/e2e/live/mcp-bridge-phases.ts, test/e2e/live/mcp-bridge.test.ts	Restores shields, restarts and health-checks the gateway, validates filesystem and MCP state, and wires the new phase into the Hermes shard test.
Managed transaction rollback test/e2e/live/mcp-bridge-hermes-lifecycle.ts	Injects a reload failure and verifies restoration of configuration bytes, hash anchors, gateway health, and the current integrity state.

Workflow report test timeout

Layer / File(s)	Summary
Workflow report timeout test/e2e/support/e2e-report-to-pr-workflow-boundary.test.ts	Sets an explicit 40,000-millisecond timeout for the planner matrix workflow-output test.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant HermesTest
  participant SandboxClient
  participant HermesGateway
  participant TransactionHelper
  HermesTest->>SandboxClient: restore shields and restart gateway
  SandboxClient->>HermesGateway: run health checks
  HermesGateway-->>SandboxClient: report healthy status
  HermesTest->>TransactionHelper: run managed add with injected reload failure
  TransactionHelper->>HermesGateway: attempt reload
  HermesGateway-->>TransactionHelper: fail first reload
  TransactionHelper->>TransactionHelper: restore config and hash anchors
  TransactionHelper->>HermesGateway: perform rollback reload
  HermesGateway-->>TransactionHelper: report success
  TransactionHelper-->>HermesTest: return current integrity state

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7743: Adds overlapping Hermes MCP restart and integrity regression coverage.
• NVIDIA/NemoClaw#7759: Changes the same workflow boundary test timeout.

Suggested labels: area: e2e, bug-fix

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The fix and regression test address the stale config-hash restart failure, rollback behavior, shields restoration, and integrity guarantees from #7499.
Out of Scope Changes check	✅ Passed	The only extra change is a test timeout increase, which is incidental support for the new e2e coverage and not unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and matches the main theme: Hermes/MCP integrity validated through restart behavior.

✨ 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/7499-hermes-mcp-integrity-restart-v2

---

_{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 8481c68 in the codex/7499-hermes-mc... branch remains at 96%, unchanged from commit 0fe7ed7 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 8481c68 in the codex/7499-hermes-mc... branch remains at 81%, unchanged from commit cf34b72 in the main branch.

Show a code coverage summary of the most impacted files.

File	main cf34b72	codex/7499-hermes-mc... 8481c68	+/-
src/lib/onboard...ndbox-create.ts	83%	33%	-50%
src/lib/onboard...-create-plan.ts	88%	75%	-13%
src/lib/onboard...ndbox-create.ts	91%	83%	-8%
src/lib/sandbox...rce-identity.ts	88%	88%	0%

---

_{Updated July 28, 2026 23:06 UTC}

[coderabbitai]

🧹 Nitpick comments (1)

test/e2e/live/mcp-bridge-hermes-lifecycle.ts (1)

243-259: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use the public inspect flow for the rollback assertion

The rollback check is coupled to the production string config and hashes were restored and to private helpers like _assert_non_root_lifecycle_identity(), _gateway_healthy(), and _load_guard(). The same integrity state is already available through the public inspect path, so this can stay on the supported boundary and avoid brittle internal-shape coupling.

🤖 Prompt for 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.

In `@test/e2e/live/mcp-bridge-hermes-lifecycle.ts` around lines 243 - 259, Update
the rollback assertion in the lifecycle test to use the public inspect flow
instead of matching the production message or calling
_assert_non_root_lifecycle_identity(), _gateway_healthy(), and _load_guard().
Assert rollback success and current integrity through the supported inspect
interface, while preserving the exact restoration check for config and hash
files.

Source: Path instructions

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

Nitpick comments:
In `@test/e2e/live/mcp-bridge-hermes-lifecycle.ts`:
- Around line 243-259: Update the rollback assertion in the lifecycle test to
use the public inspect flow instead of matching the production message or
calling _assert_non_root_lifecycle_identity(), _gateway_healthy(), and
_load_guard(). Assert rollback success and current integrity through the
supported inspect interface, while preserving the exact restoration check for
config and hash files.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 3129b38a-d910-41c1-b6c7-e7b32cd504e6

📥 Commits

Reviewing files that changed from the base of the PR and between 71a7856 and c4f421c.

📒 Files selected for processing (3)

• test/e2e/live/mcp-bridge-hermes-lifecycle.ts
• test/e2e/live/mcp-bridge-phases.ts
• test/e2e/live/mcp-bridge.test.ts

[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 · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections match; severity counts match.

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-inference, cloud-onboard, security-posture, mcp-bridge, mcp-bridge-dev

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 `@scripts/managed-gateway-control.py`:
- Around line 1352-1362: Update _parse_locked_hermes_hash in
scripts/managed-gateway-control.py at lines 1352-1362 to raise ValueError
whenever a normal hash record is encountered after mcp_state_seen, enforcing
terminal MCP metadata ordering. Add state-first and state-between-records
fixtures in test/managed-gateway-control.test.ts at lines 44-51, asserting both
produce GATEWAY_CONFIG_HASH_MISMATCH.

🪄 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: a7fd23ff-fbea-429c-b29a-ee9799a67463

📥 Commits

Reviewing files that changed from the base of the PR and between 1f60079 and 855979c.

📒 Files selected for processing (3)

• scripts/managed-gateway-control.py
• test/e2e/live/mcp-bridge-hermes-lifecycle.ts
• test/managed-gateway-control.test.ts

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

• test/e2e/live/mcp-bridge-hermes-lifecycle.ts

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