feat(policy): add sandbox policy get command for clean YAML output

[kagura-agent]

Summary

Adds nemoclaw <name> policy-get, a public command that exports the sandbox's round-trippable OpenShell base policy as validated YAML.
The default output strips the OpenShell metadata header and is suitable for review, editing, and openshell policy set; --raw preserves the unparsed metadata-bearing response for diagnostics only.

Related Issue

Closes #6052.

Changes

• Add the sandbox:policy:get oclif command and the public <name> policy-get route.
• Read openshell policy get --base, not the effective --full policy, so provider-composed reserved entries are never advertised as round-trippable.
• Fail closed on empty, malformed, or unsuccessful policy reads while preserving an explicit diagnostic-only --raw mode.
• Add composed fake-OpenShell coverage for exact argv, metadata stripping, YAML parsing, malformed output, and subprocess failure.
• Replace the repeated shell/awk metadata workaround in the policy documentation and regenerate the NemoHermes command reference.

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 — read-only argv execution, fail-closed parsing, and the --base mutation boundary were reviewed and covered by the repository policy-read audit.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Git hooks passed during commit and push, and npx prek run --from-ref origin/main --to-ref HEAD passes
• Targeted tests pass for changed behavior
• Full npm test passes (broad runtime changes only) — not run; the change is covered by focused CLI, integration, and package-contract tests.
• 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) — the build passes with 0 errors and 2 pre-existing hidden warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only) — not applicable; no new pages were added.

Attribution

Original implementation and PR authorship are by @kagura-agent.
Kagura's two original GitHub-Verified commits, including the original Claude Opus 4 co-authorship trailer, are preserved unchanged.

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• New Features

  • Added a new policy-get command to export a sandbox’s base network policy, with an option to print the raw output.

• Documentation

  • Updated CLI and network policy guides to use the new export-and-reapply workflow.
  • Clarified when to use raw output and when validation failures cause the command to exit.

• Tests

  • Added coverage for policy export behavior, raw output handling, error cases, and command translation compatibility.

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

[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

Adds a new getSandboxPolicy action and sandbox:policy:get oclif command that exports a sandbox's round-trippable base network policy (raw or parsed YAML), wires CLI route translation, extends the mutation-read audit allowlist, and updates network-policy documentation and command references accordingly.

Changes

Sandbox Policy Get Flow

Layer / File(s)	Summary
Policy export action src/lib/actions/sandbox/policy-get.ts	Adds PolicyGetResult interface and getSandboxPolicy(sandboxName) which captures raw OpenShell base-policy output and parses it into YAML when present.
Command surface, execution, and CLI route wiring src/commands/sandbox/policy/get.ts, test/package-contract/cli/public-argv-translation.test.ts	Adds SandboxPolicyGetCommand with --raw flag and error handling for missing raw/parsed output, and updates argv translation tests/route overrides to map legacy policy-get to sandbox:policy:get.
Command and action tests src/commands/sandbox/policy/get.test.ts, src/lib/actions/sandbox/policy-get.test.ts	Adds Vitest suites covering success, --raw, empty-result, parse-failure, and thrown-error scenarios for both the command and the underlying action.
Docs and audit updates docs/network-policy/customize-network-policy.mdx, docs/network-policy/integration-policy-examples.mdx, docs/reference/cli-selection-guide.mdx, docs/reference/commands.mdx, docs/reference/network-policies.mdx, scripts/checks/openshell-policy-mutation-read.ts	Replaces prior openshell policy get --base shell-pipeline instructions with the new $$nemoclaw <name> policy-get export workflow across docs, documents the new command and --raw flag, updates policy-add behavior description, and extends the mutation-read audit allowlist for the new action.

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

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant SandboxPolicyGetCommand
  participant getSandboxPolicy
  participant runCapture
  participant parseCurrentPolicy

  User->>SandboxPolicyGetCommand: sandbox:policy:get <name> [--raw]
  SandboxPolicyGetCommand->>getSandboxPolicy: getSandboxPolicy(name)
  getSandboxPolicy->>runCapture: openshell policy get --base <name>
  runCapture-->>getSandboxPolicy: raw output
  alt raw non-empty
    getSandboxPolicy->>parseCurrentPolicy: parse(raw)
    parseCurrentPolicy-->>getSandboxPolicy: yaml
  end
  getSandboxPolicy-->>SandboxPolicyGetCommand: { raw, yaml }
  alt --raw flag set
    SandboxPolicyGetCommand->>User: log raw
  else no raw
    SandboxPolicyGetCommand->>User: log yaml
  end

Loading

Related issues: #6052

Suggested labels: documentation, enhancement, cli

Suggested reviewers: (none identified from provided context)

Poem

A rabbit taps the sandbox gate,
exports the base, both raw and straight,
strips the header, keeps it clean,
yaml hops from the machine,
--raw warns "don't reapply this state!"

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding a sandbox policy get command that emits clean YAML.
Linked Issues check	✅ Passed	The new policy-get command strips metadata by default and keeps --raw for diagnostics, which addresses the round-trip parse failure in #6052.
Out of Scope Changes check	✅ Passed	The docs, tests, and audit allowlist changes all support the new policy export command and its round-trip behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

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

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

Tests assert mock calls instead of observable output.

Both the default-parsing test and the --raw test verify only that internal helpers were invoked with certain args, never that the command actually logs the expected YAML/raw content. This locks tests to implementation details rather than the command's public behavior (what a user sees on stdout), and would mask a behavioral regression while still passing.

As per path instructions, tests should "Prefer observable outcomes through the public boundary over source-text, private-shape, or mock-call assertions."

✅ Suggested addition: assert on logged output

+  it("invokes openshell and parses policy by default", async () => {
     const rawOutput =
       "Version: 1\nHash: abc\nStatus: active\n---\nversion: 1\nnetwork_policies: []";
     mocks.runCapture.mockReturnValue(rawOutput);
     mocks.parseCurrentPolicy.mockReturnValue("version: 1\nnetwork_policies: []");

+    const logSpy = vi.spyOn(SandboxPolicyGetCommand.prototype, "log");
     await SandboxPolicyGetCommand.run(["alpha"], rootDir);

     expect(mocks.assertOpenshellResolvable).toHaveBeenCalled();
     expect(mocks.buildPolicyGetCommand).toHaveBeenCalledWith("alpha");
     expect(mocks.runCapture).toHaveBeenCalledWith([...]);
     expect(mocks.parseCurrentPolicy).toHaveBeenCalledWith(rawOutput);
+    expect(logSpy).toHaveBeenCalledWith("version: 1\nnetwork_policies: []");
   });

🤖 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/get.test.ts` around lines 29 - 58, The
SandboxPolicyGetCommand tests are only checking internal helper calls instead of
the command’s observable output. Update the tests around
SandboxPolicyGetCommand.run to assert the stdout/logged result for both the
default parsed YAML path and the --raw path, using the mocked runCapture output
as the public boundary. Keep the helper setup assertions only if needed for
setup, but make the primary expectation the actual emitted content so the tests
validate user-visible behavior rather than implementation details.

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 `@src/commands/sandbox/policy/get.ts`:
- Around line 36-58: Move the orchestration out of SandboxPolicyGetCommand.run()
and into a sandbox action under src/lib/actions/sandbox, since run() is
currently doing precondition checks, executing OpenShell, and handling parse
branches. Extract the policy retrieval and parsing flow
(assertOpenshellResolvable, buildPolicyGetCommand, runCapture,
parseCurrentPolicy) into a typed action such as getSandboxPolicy, then keep the
command as thin argv/flag parsing plus translating the action result into
this.log/this.error. Preserve the raw/raw-flag and YAML parsing behavior in the
action’s returned result so the command no longer owns product logic.

---

Nitpick comments:
In `@src/commands/sandbox/policy/get.test.ts`:
- Around line 29-58: The SandboxPolicyGetCommand tests are only checking
internal helper calls instead of the command’s observable output. Update the
tests around SandboxPolicyGetCommand.run to assert the stdout/logged result for
both the default parsed YAML path and the --raw path, using the mocked
runCapture output as the public boundary. Keep the helper setup assertions only
if needed for setup, but make the primary expectation the actual emitted content
so the tests validate user-visible behavior rather than implementation details.

🪄 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: ece117d6-bea0-4744-adfe-63a0598ad246

📥 Commits

Reviewing files that changed from the base of the PR and between 9df364c and 6956c71.

📒 Files selected for processing (2)

• src/commands/sandbox/policy/get.test.ts
• src/commands/sandbox/policy/get.ts

[wscurran]

✨ Thanks for the fix. Adding a new nemoclaw sandbox policy get command for clean YAML output solves the get/set round-trip issue cleanly.

---

Related open issues:

• #6052 [macOS][Policy&Network] openshell policy get --full output cannot be used directly with policy set — metadata header causes YAML parse failure

[kagura-agent]

Thanks @wscurran! Happy to hear the approach works well. Let me know if you'd like any changes — happy to iterate.

[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 `@docs/reference/cli-selection-guide.mdx`:
- Around line 222-223: Clarify the ambiguous --full reference in the
policy-selection guide by tying it to the correct command. Update the sentence
near the references to policy-get and policy set so it explicitly says that
openshell policy get --full is used to inspect the effective policy, while
$$nemoclaw <name> policy-get remains the round-trippable base-policy path. Keep
the existing guidance but name the command directly so readers do not confuse
--full with a policy-get flag.

🪄 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: 16aa82c3-ef4b-4aa8-b9c7-013704cb83d6

📥 Commits

Reviewing files that changed from the base of the PR and between b5d9872 and 8ebcb15.

📒 Files selected for processing (9)

• docs/network-policy/customize-network-policy.mdx
• docs/network-policy/integration-policy-examples.mdx
• docs/reference/cli-selection-guide.mdx
• docs/reference/commands-nemohermes.mdx
• docs/reference/commands.mdx
• docs/reference/network-policies.mdx
• scripts/checks/openshell-policy-mutation-read.ts
• src/commands/sandbox/policy/get.test.ts
• src/commands/sandbox/policy/get.ts

💤 Files with no reviewable changes (5)

• scripts/checks/openshell-policy-mutation-read.ts
• src/commands/sandbox/policy/get.ts
• src/commands/sandbox/policy/get.test.ts
• docs/reference/network-policies.mdx
• docs/reference/commands.mdx

[kagura-agent]

Hi @wscurran 👋 Thanks again for the positive feedback! Just checking in — is there anything else needed for this to move toward merge? Happy to address any additional changes. 🌸

[cv]

Reviewed the current head. The command reuses the existing fail-closed OpenShell policy parser, gates unparsed metadata behind --raw, wires the public CLI route, and includes focused command, action, package-contract, and documentation tests. Current-head CI and contributor-compliance gates are green.

[cv]

Re-reviewed after the conflict-free main update. The reviewed policy-get implementation is unchanged relative to current main, all current-head CI and compliance gates pass, and the merge commit is GitHub Verified.