fix(policy): accept acknowledgement flags on policy restore

[laitingsheng]

Summary

policy restore rejected --yes, -y, and --force, so a script that excluded a baseline entry non-interactively could not restore it the same way. Restore now reports whether it will re-allow current egress or clear only a stale exclusion record, then requires the same explicit acknowledgement as policy exclude. Both commands now show one supported flag set in root help. Restore also binds the mutation to the baseline entry or confirmed absence shown before acknowledgement and stops if that target changes.

Related Issue

Fixes #8114

Changes

• Bind policy restore to policyMutationFlags and remove the restore-only flag definition.
• Report the current scope or stale-record action before acknowledgement.
• Require --force or --yes in non-interactive mode and exit without mutation when standard input closes before acknowledgement.
• Keep --dry-run non-mutating.
• Bind restore to the baseline entry digest or confirmed absence shown before acknowledgement, and stop without journal, registry, or live-policy mutation if it changes.
• Reject an unreadable recorded-agent baseline before any journal, registry, or live-policy mutation.
• Remove the unsupported -f alias from exclude help and display the complete exclude and restore command signatures.
• Document restore flags, egress disclosure, stale-record handling, and unattended recovery commands.
• Cover parser behavior, acknowledgement outcomes, and root-help metadata.

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 nine-category Codex Desktop review passed for final commit f6b766fd69adaf7c7ed2adb6c054272b739e5f24 with no findings. Restore is bound to the disclosed digest or explicit absence before reconciliation or mutation, and unreadable recorded-agent baselines stop without effects.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: None requested; every required check must pass.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Independent Codex Desktop review passed for final commit f6b766fd69adaf7c7ed2adb6c054272b739e5f24 against current main 04ff661211837b78c649ffcdbb89d81588e62ae6. The complete PR diff and the final unreadable-baseline no-effects fix were reviewed. docs/reference/commands.mdx and docs/reference/network-policies.mdx preview restored egress or stale-record cleanup before acknowledgement and document --force, --yes, -y, and nonmutating --dry-run. Both changed preview errors use the controlled term Rerun. GitHub CI provides documentation validation.
• Agent: Codex Desktop

Security Review

• Result: PASS
• Reviewed commit: f6b766fd69adaf7c7ed2adb6c054272b739e5f24
• Base commit: 04ff661211837b78c649ffcdbb89d81588e62ae6
• Secrets and credentials: PASS
• Input validation and data sanitization: PASS
• Authentication and authorization: PASS
• Dependencies and third-party libraries: PASS
• Error handling and logging: PASS
• Cryptography and data protection: PASS
• Configuration and security controls: PASS
• Security testing: PASS
• System security: PASS
• Evidence: Restore records the canonical digest of the disclosed baseline entry or explicit absence, re-resolves it before transaction recovery, and returns without capture, policy push, journal, registry, or exclusion mutation when the baseline is unreadable or changes. Restoration journals before widening live egress and finalizes only after exact live verification. Regression cases cover an entry changing, appearing, disappearing, and becoming unreadable; acknowledgement, dry-run, decline, and closed-input paths remain fail-closed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable
• Station profile/scenario: Not applicable
• Result: Not applicable; this PR does not change scripts/prepare-dgx-station-host.sh.
• Supporting evidence: Not applicable

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub — the final commit is signed and GitHub reports it as verified.
• 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 — normal commit hooks and the final pre-push hook passed.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — GitHub CI is authoritative and running for the final commit.
• Applicable broad gate passed — GitHub CI is authoritative and running for the final commit.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, credentials, or private keys are added by this diff.
• npm run docs builds without warnings (doc changes only) — GitHub documentation checks are running for the final commit.
• Doc pages follow the style guide (doc changes only) — independent documentation review passed.
• New doc pages include SPDX header and frontmatter (new pages only) — Not applicable; no new documentation page was added.

GitHub CI is authoritative.
No duplicate local test, documentation, build, or typecheck suite ran after the merge refresh.

Behavior note for reviewers: this makes policy restore stop on a confirmation prompt where it previously applied immediately. Unattended callers that ran bare policy restore <key> need --force or --yes.

---

Signed-off-by: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• New Features

  • Policy restoration now requires explicit confirmation with --force or --yes.
  • Interactive restores prompt before re-enabling egress and handle declined or incomplete input.
  • --dry-run previews restoration changes without applying them.
  • Restores safely stop when the previewed policy entry has changed.
  • Stale exclusions can be cleared without restoring unavailable egress.
  • Policy exclusions and restores require an explicit key; the -f alias is no longer advertised.

• Documentation

  • Updated policy guides with confirmation requirements, preview behavior, migration guidance, stale-record cleanup, and revised examples.

[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

policy restore now accepts --force and --yes/-y. Interactive restoration prompts for confirmation, while non-interactive restoration requires explicit acknowledgement. Restoration validates the previewed baseline before mutation. Documentation and tests cover the updated behavior.

Changes

Policy restore acknowledgement and validation

Layer / File(s)	Summary
Preview-bound restoration src/lib/policy/index.ts, src/lib/policy/baseline-exclusion-persistence.test.ts	Restoration validates the current baseline digest before recovery. Stale-record cleanup waits for a successful live-policy read. Tests cover changed, added, and removed baseline entries without mutation.
Restore acknowledgement enforcement src/lib/actions/sandbox/policy-channel.ts, src/lib/actions/sandbox/policy-channel-baseline.test.ts, src/lib/sandbox/policy-command-support.ts	Restoration enforces acknowledgement, prompts interactive callers, handles stdin EOF, and preserves dry-run behavior. Tests cover accepted, rejected, declined, and non-mutating flows.
Restore command flag wiring src/commands/sandbox/policy/restore.ts, src/commands/sandbox/policy/mutate.test.ts, src/commands/sandbox/policy/exclude.ts, src/lib/cli/public-display-defaults.ts, test/root-help.test.ts	The restore command uses shared mutation flags and maps --yes/-y and --force correctly. Display metadata and root help document the supported flags. The exclude usage text no longer advertises -f.
Restore documentation updates docs/reference/commands.mdx, docs/reference/network-policies.mdx	Documentation covers keyed restore, explicit acknowledgement, dry-run behavior, baseline recovery, stale-record cleanup, and release migration guidance.

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

Sequence Diagram(s)

sequenceDiagram
  participant PolicyRestoreCommand
  participant restoreSandboxBaselineUnlocked
  participant restoreBaselineEntry
  participant LivePolicy
  PolicyRestoreCommand->>restoreSandboxBaselineUnlocked: pass force, yes, and dry-run options
  restoreSandboxBaselineUnlocked->>restoreSandboxBaselineUnlocked: require acknowledgement or prompt
  restoreSandboxBaselineUnlocked->>restoreBaselineEntry: pass expected target digest
  restoreBaselineEntry->>LivePolicy: validate current baseline and read live policy
  restoreBaselineEntry->>restoreBaselineEntry: restore or clear stale exclusion

Loading

Suggested labels: area: docs

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #8114 by adding --yes, -y, and --force support with non-interactive acknowledgement behavior for policy restore.
Out of Scope Changes check	✅ Passed	The changes remain within scope because documentation, safety checks, prompts, and tests support policy restore acknowledgement and automation parity.
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 clearly identifies the main change: adding acknowledgement flags to the policy restore command.

✨ 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 fix/policy-restore-acknowledgement-flags

---

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

[github-actions]

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit f6b766f in the fix/policy-restore-a... branch remains at 96%, unchanged from commit 453b5df in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit f6b766f in the fix/policy-restore-a... branch remains at 81%, unchanged from commit a556201 in the main branch.

Show a code coverage summary of the most impacted files.

File	main a556201	fix/policy-restore-a... f6b766f	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/policy/index.ts	59%	59%	0%
src/lib/shields/index.ts	70%	70%	0%
src/lib/actions...licy-channel.ts	80%	81%	+1%
src/lib/actions...all/run-plan.ts	83%	84%	+1%
src/lib/inferen...ving/catalog.ts	91%	93%	+2%
src/lib/onboard...eway-process.ts	95%	97%	+2%
src/lib/state/g...way-registry.ts	94%	97%	+3%
src/lib/onboard...eway-cleanup.ts	59%	66%	+7%
src/lib/actions...ateway-ports.ts	0%	93%	+93%

---

_{Updated August 04, 2026 06:06 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 · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections differ; severity counts match.

3 terminology differences from the second opinion

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

• stale exclusion at docs/reference/commands.mdx:1976: selected only by the second-opinion lane as justified.
• Rerun at src/lib/policy/index.ts:1335: selected only by the second-opinion lane as established.
• acknowledgement at docs/reference/commands.mdx:1988: selected only by the second-opinion lane as established.

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 — explicit acknowledgement at docs/reference/commands.mdx:1988: Keep the established term. The documentation identifies the required flags and dry-run exception.
• established — stale exclusion record at docs/reference/commands.mdx:1978: Keep the established term. It distinguishes stale-record cleanup from egress restoration.
• justified — current baseline egress at docs/reference/commands.mdx:1975: Keep the modifier because it identifies the previewed release-baseline scope bound before acknowledgement.

E2E guidance

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

Recommended E2E: cloud-inference, security-posture, channels-add-remove, channels-stop-start, inference-routing, network-policy, onboard-repair, onboard-resume, rebuild-openclaw, state-backup-restore

1 optional E2E recommendation

• snapshot-commands

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: 4

🧹 Nitpick comments (1)

src/commands/sandbox/policy/mutate.test.ts (1)

95-113: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover the long --yes spelling.

This test covers -y and --force, but the restore contract includes --yes, -y, and --force. Add a public command invocation with --yes and assert yes: true. Otherwise, a parser regression in the long spelling can pass.

Proposed test addition

+    await PolicyRestoreCommand.run(["alpha", "nous_research", "--yes"], rootDir);
+    expect(mocks.restoreSandboxBaseline).toHaveBeenLastCalledWith("alpha", {
+      key: "nous_research",
+      yes: true,
+      force: false,
+      dryRun: false,
+    });

As per path instructions, review tests for behavioral confidence rather than implementation lock-in.

🤖 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 `@src/commands/sandbox/policy/mutate.test.ts` around lines 95 - 113, Add
coverage in the existing “accepts the same acknowledgement flags on restore as
on exclude (`#8114`)” test for invoking PolicyRestoreCommand with the long “--yes”
flag, and assert restoreSandboxBaseline receives yes: true. Keep the existing
short “-y” and “--force” assertions intact.

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.

Inline comments:
In `@docs/reference/commands.mdx`:
- Around line 1962-1963: Update the recovery guidance around the changed-entry
instructions to show complete host CLI invocations, including $$nemoclaw and the
relevant sandbox name before policy restore and policy exclude. Preserve the
existing command options, sequencing, and distinction between changed and
removed entries.

In `@src/lib/actions/sandbox/policy-channel-baseline.test.ts`:
- Around line 201-207: Strengthen the test case in “requires explicit
acknowledgement in non-interactive mode (`#8114`)” by asserting the captured error
includes “Non-interactive restore requires explicit acknowledgement” and
verifying promptMock was not called. Keep the existing exit-code and
restoreBaselineEntryMock assertions.

In `@src/lib/actions/sandbox/policy-channel.ts`:
- Around line 2017-2021: Update the missing-key usage message in
restoreSandboxBaselineUnlocked to list every supported acknowledgement flag,
including --yes|-y alongside --force, while preserving the existing key and
dry-run usage details.
- Around line 2057-2066: Update restoreSandboxBaseline’s acknowledgement flow to
catch askPrompt rejection with code "EOF" when stdin closes, handling it through
the closed-stdin error path without mutating the sandbox. Add a regression test
covering closed stdin with NEMOCLAW_NON_INTERACTIVE unset and assert that no
restore mutation occurs.

---

Nitpick comments:
In `@src/commands/sandbox/policy/mutate.test.ts`:
- Around line 95-113: Add coverage in the existing “accepts the same
acknowledgement flags on restore as on exclude (`#8114`)” test for invoking
PolicyRestoreCommand with the long “--yes” flag, and assert
restoreSandboxBaseline receives yes: true. Keep the existing short “-y” and
“--force” assertions intact.

🪄 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: 827299e0-3ab8-44bd-864a-6a7d4979fea0

📥 Commits

Reviewing files that changed from the base of the PR and between 4cd4d64 and 1e4243e.

📒 Files selected for processing (8)

• docs/reference/commands.mdx
• docs/reference/network-policies.mdx
• src/commands/sandbox/policy/exclude.ts
• src/commands/sandbox/policy/mutate.test.ts
• src/commands/sandbox/policy/restore.ts
• src/lib/actions/sandbox/policy-channel-baseline.test.ts
• src/lib/actions/sandbox/policy-channel.ts
• src/lib/sandbox/policy-command-support.ts

💤 Files with no reviewable changes (1)

• src/lib/sandbox/policy-command-support.ts

[apurvvkumaria]

Reviewed current head 1e4243e. The restore confirmation now fails closed in non-interactive mode without acknowledgement, previews scope before mutation, preserves dry-run behavior, and correctly wires --yes/-y/--force. Required CI and E2E pass. I found no blocking correctness, security, compatibility, or regression issue.

[apurvvkumaria]

Approve — reviewed exact head 652ed64. Restore now discloses the exact live or stale-record action before acknowledgement, returns without mutation for dry-run, refusal, non-interactive missing acknowledgement, and closed stdin, and retains the existing locked restore transaction. Flag parsing coverage passes 8 of 8; the exact CI CLI failure is the same unrelated managed-image registry fetch timeout seen across current branches. No blocking correctness, security, compatibility, or regression defect found.

[coderabbitai]

🧹 Nitpick comments (1)

test/root-help.test.ts (1)

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

Add the linked issue suffix to the test title.

This test covers issue #8114. Add (#8114) as the final title suffix.

Proposed change

-  it("shows the supported policy acknowledgement flags", () => {
+  it("shows the supported policy acknowledgement flags (`#8114`)", () => {

🤖 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/root-help.test.ts` at line 66, Update the test title in the shows the
supported policy acknowledgement flags test to append the linked issue suffix
"(`#8114`)" as the final text.

Source: Coding guidelines

🤖 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/root-help.test.ts`:
- Line 66: Update the test title in the shows the supported policy
acknowledgement flags test to append the linked issue suffix "(`#8114`)" as the
final text.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e377c69e-2a21-4d75-8de6-f1f3cc142816

📥 Commits

Reviewing files that changed from the base of the PR and between 4991b3b and 889fca5.

📒 Files selected for processing (2)

• src/lib/cli/public-display-defaults.ts
• test/root-help.test.ts

[apurvvkumaria]

Comment — reviewed exact head 889fca5. The new root-help metadata now matches the actual policy exclude and restore contract: key is required, --force has no -f alias, and --yes/-y plus --dry-run are supported. The targeted root-help assertion, all eight CLI shards, CLI tests, static checks, installer integration, platform E2E, and security scans pass. No blocking correctness, security, compatibility, or regression defect found; the code is safe. Non-blocking fast follow: update the two docs/reference/commands.mdx headings to include in a narrowly scoped docs-only PR. That restores the currently failing help/docs parity gate without changing runtime behavior.

[apurvvkumaria]

Approve — re-reviewed exact head cec7efe. The only PR-specific change since the prior current-head comment adds the required key positional argument to the policy exclude and restore documentation headings, aligning them with root help and resolving the attributable CLI-parity mismatch. The intervening main merges do not change the acknowledgement implementation. No blocking correctness, security, compatibility, documentation, or regression defect remains.

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@docs/reference/network-policies.mdx`:
- Line 348: Update the restore acknowledgement documentation near the existing
`--dry-run` statement to include both `--yes` and its short form `-y`, while
retaining `--force` as supported. Clearly distinguish interactive callers, which
are prompted for confirmation, from non-interactive callers, which must provide
an acknowledgement flag unless using `--dry-run`, based on the contract in the
restore command implementation.
- Line 317: Update the sentence near the documented egress behavior to remove
the first repeated occurrence of “again,” leaving the remaining wording and
meaning unchanged.
- Line 327: Update the network policy documentation’s release-removal scenario
to show the exact error emitted by policy exclude <key>: Unknown baseline entry
'<key>'. Preserve the explanation that the failure occurs because no baseline
entry remains to exclude.

🪄 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: d8ba0c95-5ca8-4e9f-92ff-5bf48774d55d

📥 Commits

Reviewing files that changed from the base of the PR and between cec7efe and 69def28.

📒 Files selected for processing (6)

• docs/reference/commands.mdx
• docs/reference/network-policies.mdx
• src/lib/actions/sandbox/policy-channel-baseline.test.ts
• src/lib/actions/sandbox/policy-channel.ts
• src/lib/policy/baseline-exclusion-persistence.test.ts
• src/lib/policy/index.ts

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

• docs/reference/commands.mdx