fix(shields): preserve managed MCP policies

[jyaunches]

Summary

nemoclaw shields down replaced the complete live OpenShell policy and dropped generated policy entries for registered Model Context Protocol (MCP) servers. This change reconciles only exact NemoClaw-managed MCP entries during Shields transitions, so a surviving server remains reachable while removed servers stay removed.

Stacked on prerequisite #8130, which makes Shields deadline recovery serialize with lifecycle mutations without signaling the lock owner, this focused fix supersedes the MCP portion of #7980.

Related Issue

Fixes #7952

Changes

• Prove managed MCP policy ownership from exact agreement between the sandbox registry, committed generated-policy record, and live gateway policy.
• Save the owned MCP key manifest with the Shields snapshot, remove snapshot-time managed entries during restoration, and overlay only current exact entries.
• Fail closed on ambiguous, stale, incomplete, malformed, or legacy ownership during manual transitions. At an expired deadline, omit unproven managed MCP entries and audit the omission instead of extending the Shields-down window.
• Preserve current managed MCP entries when building the permissive runtime policy, while rejecting an unreadable or ambiguous live policy.
• Clean staged runtime policy files across early failure paths.
• Restore the Hermes live regression assertions at the actual failure boundary and around the unrelated server lifecycle.
• Document MCP policy reconciliation for manual and automatic restoration.

Failure Timing and Hermes Upgrade Context

The original journey had a hidden Shields lifecycle between the first successful call to server A and the later lifecycle for server B:

1. Run shields up.
2. Restart the Hermes gateway.
3. Run shields down.
4. Exercise the configuration rollback path.
5. Add and remove B.
6. Call A.

Boundary instrumentation recorded in #7952 showed that A remained healthy through Shields up and the gateway restart. It became unusable immediately after Shields down, which dropped A's generated MCP policy. The later failure after B was removed was only where the test noticed the already-broken route; B removal was a misleading correlation.

This surfaced during the Hermes upgrade work because new coverage and upgrade repairs landed nearly back-to-back:

• test(hermes): cover MCP integrity through restart #7761 added the Hermes MCP helper containing Shields up, gateway restart, Shields down, and rollback. Its verification collected and imported the live target but did not run the complete live E2E.
• chore(hermes): upgrade Hermes Agent to v2026.7.20 #7771 upgraded Hermes the next day, but its selected E2Es skipped the mcp-bridge target.
• fix(hermes): repair v0.19 runtime migrations #7849 repaired Hermes 0.19 migrations and updated MCP tool naming, allowing the live test to progress far enough to expose the later failure.
• test(e2e): restart Hermes before MCP rediscovery #7866 moved the explicit mcp restart A before the first post-removal call. Restart reapplied A's generated policy and masked the missing-policy state.

The corrected regression order is:

1. Run shields up.
2. Restart the Hermes gateway.
3. Run shields down.
4. Call A immediately.
5. Exercise the configuration rollback path.
6. Add B, prove the DNS-rebinding connection is denied, remove B, and verify that A's managed policy is unchanged while B's policy is gone.
7. Call A before the later explicit restart.
8. Capture the authenticated rediscovery offset.
9. Run mcp restart A without resupplying the secret.
10. Call A and verify authenticated rediscovery.

Whole-policy Shields replacement and the filesystem-only runtime merge predate the Hermes upgrade. This is a latent NemoClaw Shields policy-composition defect detected by expanded Hermes regression coverage, not a Hermes upgrade regression.

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:
• 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-head Codex security review passed all nine categories at 18039569796d6ac7604de032edb7abf84f2c73c4; no findings.
• 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: docs-updated
• Evidence: Reviewed docs/manage-sandboxes/runtime-controls.mdx and docs/reference/commands.mdx, all rendered guide variants, changed operator-facing text, comments, test titles, and the Hermes E2E chronology. Verified claims against source, issue Shields down drops registered MCP policies from the effective gateway policy #7952, and PRs test(hermes): cover MCP integrity through restart #7761, chore(hermes): upgrade Hermes Agent to v2026.7.20 #7771, fix(hermes): repair v0.19 runtime migrations #7849, and test(e2e): restart Hermes before MCP rediscovery #7866. npm run docs completed with 0 errors and 2 existing Fern warnings.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh is unchanged.
• 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
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Focused CLI 123/123, integration 11/11, E2E support 13/13, npm run typecheck:cli, npm run checks:repository, test-size guardrail, E2E semantic phase plans, and serial npm run test:changed 674/674 passed.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Standard PR CI run 30824992396 passed. One inherited 50 ms lifecycle-lock assertion timing flake passed on the failed-job rerun without a code change.
• 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)

npm run docs passed with 0 errors and 2 existing Fern warnings, so the warning-free checkbox remains unchecked. No new documentation pages were added.

Trusted E2E run 30826792180 passed all 10 selected checks: cloud inference, cloud onboard, security posture, inference routing, MCP bridge, MCP bridge dev, network policy, onboard repair, onboard resume, and OpenShell credential-generation window. The primary review advisor reported no findings. Nemotron completed after retrying a protocol-only failure; its one test warning requested the exact transition/state ownership-mismatch deadline regression already present in src/lib/shields/policy-transition.test.ts, which passed.

---

Signed-off-by: Julie Yaunches jyaunches@nvidia.com

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e93d4269-9e9b-46dc-a253-651418880da4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{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 1803956 in the codex/shields-mcp-po... branch remains at 96%, unchanged from commit d6ac402 in the codex/shields-deadli... branch.

TypeScript / code-coverage/cli

The overall coverage in commit 1803956 in the codex/shields-mcp-po... branch remains at 81%, unchanged from commit d6ac402 in the codex/shields-deadli... branch.

Show a code coverage summary of the most impacted files.

File	codex/shields-deadli... d6ac402	codex/shields-mcp-po... 1803956	+/-
src/lib/shields...sive-runtime.ts	96%	78%	-18%
src/lib/onboard...eway-service.ts	86%	82%	-4%
src/lib/shields...nsition-lock.ts	88%	85%	-3%
src/lib/onboard.ts	31%	31%	0%
src/lib/actions...ridge-policy.ts	66%	69%	+3%
src/lib/state/m...-acquisition.ts	75%	82%	+7%
src/lib/shields...imer-control.ts	80%	90%	+10%
src/lib/onboard...eway-cutover.ts	70%	90%	+20%
src/lib/shields...y-transition.ts	0%	94%	+94%
src/lib/state/m...er-authority.ts	0%	100%	+100%

---

_{Updated August 03, 2026 15:16 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 · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections match; Nemotron reported the same number of blockers, 1 more warning, the same number of suggestions.

8 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• managed MCP policy at docs/manage-sandboxes/runtime-controls.mdx:118: primary classified it as established; the second opinion classified it as justified.
• ownership manifest at src/lib/shields/index.ts:2796: selected only by the second-opinion lane as established.
• unproven managed MCP at docs/manage-sandboxes/runtime-controls.mdx:121: selected only by the second-opinion lane as justified.
• snapshot-time managed MCP at docs/manage-sandboxes/runtime-controls.mdx:119: selected only by the second-opinion lane as justified.
• canonical managed MCP policy at src/lib/actions/sandbox/mcp-bridge-policy.ts:202: selected only by the second-opinion lane as justified.
• Shields transition ownership at src/lib/shields/index.ts:2786: selected only by the second-opinion lane as justified.
• deadline composition at src/lib/shields/mcp-policy-transition.ts:94: selected only by the second-opinion lane as justified.
• exact managed MCP policy at src/lib/shields/flow.test.ts:422: selected only by the second-opinion lane as justified.

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — managed MCP policy at docs/manage-sandboxes/runtime-controls.mdx:118: Use managed MCP policy for these NemoClaw-owned policy entries.
• justified — exact agreement at docs/reference/commands.mdx:1175: Retain exact agreement and name the three required records where it first appears.
• justified — snapshot-time managed MCP entries at docs/manage-sandboxes/runtime-controls.mdx:119: Retain snapshot-time managed MCP entries where restoration timing distinguishes saved and current entries.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-inference, cloud-onboard, security-posture, inference-routing, mcp-bridge, mcp-bridge-dev, network-policy, onboard-repair, onboard-resume

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[apurvvkumaria]

Reviewed exact head 1803956 against its current stacked base. Exact policy ownership proof, canonical generated-policy validation, reserved-key stripping, fail-closed drift handling, and deadline restoration are sound and well covered. I found no blocking defect; exact-head CI and E2E are green. Re-review affected areas if the stacked base changes materially.