fix(policy): remove a preset the gateway enforces without a local record

[laitingsheng]

Summary

policy list reports a preset as active when either the local registry or the live gateway holds it, but policy remove consulted the registry alone and exited non-zero with Preset 'X' is not applied., so the one state policy list exists to flag — active on gateway, missing from local state — was the only state with no removal path. policy remove now builds a single removable set from both sources and uses it for the named-preset guard and the interactive picker alike, and it distinguishes a gateway it could not query from a gateway that does not hold the preset. Applying a built-in preset to a sandbox that is missing from the registry no longer returns success in silence, which closes one way that divergence is created.

Related Issue

Fixes #9295

Changes

• removeSandboxPolicyUnlocked in src/lib/actions/sandbox/policy-channel.ts derives one removable set from getAppliedPresets and getGatewayPresets, and both the named-preset guard and the selectForRemoval picker read it. Computing it once is what keeps the two entry points from disagreeing, which is the shape of the reported defect. removePreset already reconciles a gateway-held preset without a registry entry, so the CLI guard was the only obstacle. Covered by removes a preset the gateway enforces but the registry never recorded, offers a gateway-only preset in the removal picker, and lists a preset both sources hold only once in the removal picker.
• A null from getGatewayPresets means the gateway could not be queried, not that the preset is absent, so the command falls back to the registry and names the evidence it had instead of asserting the preset is not applied. Covered by names the unreachable gateway when it refuses on local state alone; the unchanged refusal path is covered by refuses a preset neither the registry nor the gateway holds.
• The built-in arm of applyPresetContent in src/lib/policy/index.ts warns when the sandbox has no registry entry instead of returning true in silence. It keeps the successful gateway mutation, because a built-in preset stays discoverable from the gateway and is now removable; the custom arm still returns false, because a custom preset is discoverable only through the registry. Covered by warns but keeps the mutation when a built-in preset cannot be recorded locally.
• src/lib/actions/sandbox/policy-channel-refresh.test.ts and policy-channel-lock.test.ts gain a getGatewayPresets stub. Without it the new gateway read in policy remove would make those unit tests spawn a real openshell policy get.
• docs/network-policy/apply-policy-presets.mdx documents removing a preset the gateway enforces without a local record, the unreachable-gateway behavior, and the unrecorded-sandbox case for maintained and custom presets. docs/reference/commands.mdx updates the policy add and policy remove reference sections to match.

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:
• 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: docs/network-policy/apply-policy-presets.mdx, docs/reference/commands.mdx. The review returned request-changes. Its blocking finding was that the persistence paragraph stated the built-in outcome without scoping it, so a reader applying a custom preset with --from-file to an unregistered sandbox would expect a gateway-active preset when the command in fact exits non-zero and the preset appears nowhere. It also found the quoted policy list row indented two spaces where formatPolicyListPresetRow emits four, no command block before the Expected output: lead-in, the gateway named without its OpenShell qualifier on first use, an unreachable-gateway sentence that did not scope its message to the named form, and both reference sections in docs/reference/commands.mdx left describing the previous behavior. All findings were verified against source and applied.
• Agent: Claude Code

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 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: npx vitest run src/lib/actions/sandbox/policy-channel-policy.test.ts src/lib/actions/sandbox/policy-channel-refresh.test.ts src/lib/actions/sandbox/policy-channel-lock.test.ts src/lib/actions/sandbox/policy-channel-list.test.ts — 4 files, 81 tests passed; npx vitest run --project integration test/policies.test.ts — 1 file, 76 tests passed. Reverting only the two changed source files fails 5 of the 6 new cases, so they guard the behavior rather than restate it; the sixth is the preserved refusal path and passes either way by design. npm run typecheck:cli and npm run lint are clean. The two fern check warnings are pre-existing — rebuilding with the doc changes stashed reports the same two.
• 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: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• New Features

  • Policy removal now detects presets enforced by the gateway, including presets missing from local state.
  • Interactive removal lists combine locally recorded and gateway-reported presets.
  • Built-in presets can be applied successfully even when local registry recording is unavailable, with a warning.

• Bug Fixes

  • Improved handling and diagnostics when gateway state cannot be queried or presets exist in neither source.

• Documentation

  • Updated policy command and preset guides to explain gateway-only presets, warnings, and offline removal behavior.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 7ebf1a6 in the fix/policy-remove-ga... branch remains at 96%, unchanged from commit 588bb6d in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 7ebf1a6 in the fix/policy-remove-ga... branch remains at 83%, unchanged from commit 588bb6d in the main branch.

Show a code coverage summary of the most impacted files.

File	main 588bb6d	fix/policy-remove-ga... 7ebf1a6	+/-
src/lib/actions...er-lifecycle.ts	94%	85%	-9%
src/lib/actions...aged-profile.ts	88%	84%	-4%
src/lib/policy/index.ts	67%	67%	0%
src/lib/agent/defs.ts	97%	97%	0%
src/lib/actions...licy-channel.ts	82%	82%	0%
src/lib/agent/r...ime-manifest.ts	100%	100%	0%
src/lib/agent/s...store-reader.ts	89%	89%	0%
src/lib/onboard...ce-lifecycle.ts	89%	93%	+4%
src/lib/cua/run...ime-manifest.ts	84%	90%	+6%
src/lib/cua/bounded-file.ts	84%	94%	+10%

---

_{Updated August 17, 2026 10:03 UTC}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: a74095b0-05a4-4879-9ace-ace59df2e29b

📥 Commits

Reviewing files that changed from the base of the PR and between 588bb6d and 7ebf1a6.

📒 Files selected for processing (8)

• docs/network-policy/apply-policy-presets.mdx
• docs/reference/commands.mdx
• src/lib/actions/sandbox/policy-channel-lock.test.ts
• src/lib/actions/sandbox/policy-channel-policy.test.ts
• src/lib/actions/sandbox/policy-channel-refresh.test.ts
• src/lib/actions/sandbox/policy-channel.ts
• src/lib/policy/index.ts
• test/policies.test.ts

Included review availability: Your plan includes up to 12 reviews per rolling hour; 11 remain after this review.

---

📝 Walkthrough

Walkthrough

The change reconciles gateway and local policy state. Built-in presets can remain active on the gateway when local recording fails. Policy removal now supports gateway-only presets and unavailable gateway queries.

Changes

Policy state reconciliation

Layer / File(s)	Summary
Built-in preset application handling src/lib/policy/index.ts, test/policies.test.ts, docs/network-policy/apply-policy-presets.mdx, docs/reference/commands.mdx	Built-in presets apply successfully when local registry recording is unavailable and emit a warning. Tests cover the gateway mutation, return status, warning, and registry restoration.
Gateway-aware preset removal src/lib/actions/sandbox/policy-channel.ts, src/lib/actions/sandbox/policy-channel-policy.test.ts, src/lib/actions/sandbox/policy-channel-lock.test.ts, src/lib/actions/sandbox/policy-channel-refresh.test.ts, docs/network-policy/apply-policy-presets.mdx, docs/reference/commands.mdx	Removal combines local and gateway presets, deduplicates names, supports gateway-only presets, reports unavailable gateway state, and updates interactive selection. Tests cover these cases.

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

Merge Risk: 🟡 Moderate · up to 7ebf1

This PR changes policy enforcement and local/gateway reconciliation behavior, with targeted validation reported clean. However, the required sensitive-path review or maintainer waiver is not recorded, so the PR is not merge-ready until that approval is completed.

Suggested reviewers: apurvvkumaria, aasthajh

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the primary fix for removing gateway-enforced presets without local records.
Linked Issues check	✅ Passed	The changes reconcile local and gateway state and enable successful removal of gateway-only presets as required by issue #9295.
Out of Scope Changes check	✅ Passed	The warning, tests, and documentation address the same gateway/local-state divergence and support the linked policy lifecycle fix.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/policy-remove-gateway-state

---

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

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-9306.docs.buildwithfern.com/nemoclaw

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · medium confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

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

• established — active on gateway, missing from local state at docs/network-policy/apply-policy-presets.mdx:125: Keep the established policy-list state text.
• established — source unverified at docs/network-policy/apply-policy-presets.mdx:125: Keep the established provenance label.
• replace — local record at docs/network-policy/apply-policy-presets.mdx:114: Use local registry record where the text means policy preset metadata.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: inference-routing

Manual-only E2E: security-posture, channels-add-remove, channels-stop-start, onboard-repair, onboard-resume, cloud-inference, network-policy
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

2 optional E2E recommendations

• onboard-policy-preset-sequencing
• ubuntu-repo-cloud-langchain-deepagents-code

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Add an end-to-end policy removal regression test

• Location: src/lib/actions/sandbox/policy-channel-policy.test.ts:403
• Category: tests
• Problem: The new tests mock both getGatewayPresets and removePreset, so they do not exercise the command-level sequence that discovers a gateway-only preset and removes its live policy entries.
• Impact: A regression in the handoff between gateway discovery and live policy mutation can again leave gateway-only egress active while the command reports success or cannot remove it.
• Recommendation: Add a fake-OpenShell regression test that returns a policy containing a gateway-only built-in preset, captures policy set, and verifies removal preserves unrelated policy entries.
• Verification: Inspect a test that invokes the policy removal path against a fake OpenShell executable and asserts the captured policy-set YAML excludes the selected preset and retains an unrelated entry.
• Test coverage: A policy command regression test removes a gateway-only built-in preset from fake OpenShell policy and verifies the captured replacement excludes only that preset's entries.
• Evidence: src/lib/actions/sandbox/policy-channel-policy.test.ts:403-450 mocks getGatewayPresets and removePreset for gateway-only removal and picker behavior. src/lib/actions/sandbox/policy-channel.ts:1989-2036 composes getGatewayPresets selection with removePreset mutation. src/lib/policy/index.ts:1064-1171 reads live policy and writes the policy document during removal.

Workflow run details

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

[cv]

Accepted scope, code review, contributor requirements, security, risky-path tests and documentation, and required checks pass on 7ebf1a6. GitHub reports MERGEABLE. The branch is behind main, which is advisory because required checks evaluated this unchanged commit against base commit 588bb6d.

[prekshivyas]

Policy removal now uses the union of locally recorded and live-gateway presets while preserving the gateway-unreachable distinction. The built-in/custom persistence asymmetry is explicit, the mutation remains fail-closed for unknown or absent presets, and user-facing documentation covers the new recovery paths.

Cross-issue sweep: no additional candidate issues found.

Security review: secrets/credentials — PASS; input validation/sanitization — PASS; authentication/authorization — PASS; dependencies — PASS; error handling/logging — PASS; cryptography/data protection — PASS; configuration/security headers — PASS; security testing — PASS; system security — PASS.