fix(cli): translate the shields exit sentinel into a clean exit code

[Dongni-Yang]

Summary

nemoclaw <sandbox> shields up / shields down crash with a raw Node traceback (unhandled DeferredShieldsExit) whenever a shields transition fails — the first symptom in #7382.

The shields library deliberately throws a DeferredShieldsExit sentinel instead of calling process.exit inside a transition-lock callback (an exit there would strand the canonical lock), with the stated contract that "public command wrappers translate this sentinel only after the lock has been released." That translation was never implemented: the shields commands pass throwOnError: true, NemoClawCommand has no catch override, the public-grammar dispatcher rethrows errors without an oclif.exit, and the CLI entry promise has no .catch — so the sentinel reaches Node's unhandled-rejection handler and prints a raw stack.

Fix

• New leaf module src/lib/shields/deferred-exit.ts holding the DeferredShieldsExit class and a name-keyed isDeferredShieldsExit guard (name-keyed so dist/src dual-loads still match; leaf so the CLI base command doesn't load the shields coordinator, and tests that mock lib/shields keep the real guard).
• NemoClawCommand.catch override: a sentinel becomes setExitCode(error.exitCode) with no reprint (every throw site already printed its failure lines via console.error); everything else delegates to oclif's default handler unchanged.

Because oclif's Command._run resolves when catch() returns, the rejection never reaches the entry promise — on both the public-grammar and native dispatch routes. The base-class placement also fixes the same latent crash via sandbox destroy (wipeAndHardenLiveSandbox) and snapshot restore (deleteSandboxForRestore), which call shieldsUp(..., { throwOnError: true }) with no catch.

Behavior after the fix, on the #7382 repro: the existing error lines (CRITICAL: OpenClaw lock rollback ..., Recovery: ...) print exactly as today, followed by a clean exit 1 — no traceback.

This PR does not change any transition/rollback semantics. The second #7382 defect (the failed rollback quarantining openclaw.json when .config-hash is missing) is a separate guard-side fix pending maintainer design review on the issue.

Tests

• src/lib/cli/nemoclaw-oclif-command.test.ts: sentinel → resolves + process.exitCode === 1 + no reprint; code-2 sentinel fidelity; non-sentinel errors still reject through the default handler.
• src/commands/sandbox/oclif-command-adapters.test.ts: ShieldsUpCommand/ShieldsDownCommand with the shields mock throwing the sentinel → clean exit code, no traceback, no reprint.

All new tests fail at HEAD and pass with the fix.

Fixes the traceback symptom of #7382 (Refs #7382 — the config-quarantine defect remains open there).

Signed-off-by: Dongni Yang dongniy@nvidia.com

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Improved shields-related CLI failure handling by translating deferred shields exit signals into the correct oclif exit codes.
  • Suppressed unnecessary error tracebacks and stderr output for these shields-related failures.
  • Preserved existing default error handling for non-shields failures.
• Tests
  • Added coverage validating shields sentinel exit codes, ensuring stderr suppression, correct exitCode propagation, and expected behavior for non-sentinel errors.

[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: 6a852f07-af47-4c52-b6a0-3e3685a3ff99

📥 Commits

Reviewing files that changed from the base of the PR and between 9187ee2 and dea8386.

📒 Files selected for processing (1)

• src/commands/sandbox/oclif-command-adapters.test.ts

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

• src/commands/sandbox/oclif-command-adapters.test.ts

---

📝 Walkthrough

Walkthrough

Adds a shared DeferredShieldsExit sentinel, translates it in NemoClawCommand.catch, preserves normal error handling, and adds coverage for shields adapters and exit-code behavior.

Changes

Deferred shields exit handling

Layer / File(s)	Summary
Exit sentinel and shields wiring src/lib/shields/deferred-exit.ts, src/lib/shields/index.ts	Defines the shared sentinel error and shape-based type guard, then imports the sentinel into shields command handling.
Command-level exit translation src/lib/cli/nemoclaw-oclif-command.ts	Maps deferred shields exits to process.exitCode and delegates other errors to oclif’s default handler.
Exit behavior tests src/lib/cli/nemoclaw-oclif-command.test.ts, src/commands/sandbox/oclif-command-adapters.test.ts	Covers sentinel exit codes, suppressed stderr output, adapter behavior, and regular failures.

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

Possibly related PRs

• NVIDIA/NemoClaw#7395 — Also translates DeferredShieldsExit into process.exitCode in shields command flows.

Suggested labels: integration: openclaw

🚥 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 summarizes the main change: converting the shields exit sentinel into a clean exit code.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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/7382-shields-sentinel-exit

---

_{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 2cc00f7 in the fix/7382-shields-sen... branch remains at 96%, unchanged from commit ccf3dd4 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 2cc00f7 in the fix/7382-shields-sen... branch remains at 80%, unchanged from commit ccf3dd4 in the main branch.

Show a code coverage summary of the most impacted files.

File	main ccf3dd4	fix/7382-shields-sen... 2cc00f7	+/-
src/lib/shields/index.ts	72%	71%	-1%
src/lib/cli/nem...clif-command.ts	100%	100%	0%
src/lib/messagi...nnels/policy.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/securit...ntial-filter.ts	93%	93%	0%
src/lib/platform.ts	84%	89%	+5%
src/lib/onboard...ndbox-create.ts	83%	91%	+8%
src/lib/onboard...-create-plan.ts	75%	88%	+13%
src/lib/onboard...ndbox-create.ts	33%	83%	+50%
src/lib/shields...eferred-exit.ts	0%	100%	+100%

---

_{Updated July 24, 2026 05:59 UTC}

[coderabbitai]

Actionable comments posted: 2

🤖 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/lib/cli/nemoclaw-oclif-command.test.ts`:
- Around line 140-153: Update the sentinel tests around
ShieldsSentinelCommand.run and DriftSentinelCommand.run to preserve and restore
the prior process.exitCode, and restore the console.error spy created by
vi.spyOn. Use try/finally blocks so both globals are restored even when
assertions or command execution fails.

In `@src/lib/shields/index.ts`:
- Around line 767-776: Update failShieldsCommand to always throw the
DeferredShieldsExit sentinel instead of terminating the process, preserving
deferred exit handling for shieldsStatus paths reached while
withSandboxMutationLock is held. Keep NemoClawCommand.catch responsible for
translating the sentinel into the exit code, and retain the existing message and
status code.

🪄 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: 0331785e-b729-4e98-a6a1-9544a55aca4f

📥 Commits

Reviewing files that changed from the base of the PR and between d13e34a and 7e1262e.

📒 Files selected for processing (5)

• src/commands/sandbox/oclif-command-adapters.test.ts
• src/lib/cli/nemoclaw-oclif-command.test.ts
• src/lib/cli/nemoclaw-oclif-command.ts
• src/lib/shields/deferred-exit.ts
• src/lib/shields/index.ts

[coderabbitai]

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
ast-grep outline src/lib/shields/index.ts --items all
rg -n -A5 -B5 '\b(completeDeferredShieldsExit|failShieldsCommand)\s*\(|\bprocess\.exit\s*\(' src/lib/shields/index.ts
rg -n -A3 -B3 '\bcompleteDeferredShieldsExit\s*\(' src

Repository: NVIDIA/NemoClaw

Length of output: 18549

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n## completeDeferredShieldsExit callers\n'
rg -n -A4 -B4 '\bcompleteDeferredShieldsExit\s*\(' src

printf '\n## DeferredShieldsExit handling and sentinel translation\n'
rg -n -A4 -B4 '\bDeferredShieldsExit\b|\bisDeferredShieldsExit\b|catch\s*\(' src/commands src/lib | sed -n '1,260p'

printf '\n## shields command entrypoints\n'
rg -n -A4 -B4 '\bshields(Status|Up|Down)\s*\(' src/commands src/lib | sed -n '1,260p'

Repository: NVIDIA/NemoClaw

Length of output: 35837

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n## command files mentioning shields\n'
git ls-files 'src/commands/**/*.ts' 'src/lib/**/*.ts' | rg 'shields|NemoClawCommand|deferred-exit|command'

Repository: NVIDIA/NemoClaw

Length of output: 6723

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n## withSandboxMutationLock\n'
rg -n -A8 -B8 '\bwithSandboxMutationLock\s*\(' src/lib src/commands | sed -n '1,220p'

printf '\n## NemoClawCommand catch/fail path\n'
rg -n -A10 -B10 '\bclass NemoClawCommand\b|\bcatch\(' src/lib/cli/nemoclaw-oclif-command.ts src/commands/root/*.ts src/commands/sandbox/shields/*.ts | sed -n '1,260p'

printf '\n## shields status command implementation\n'
cat -n src/commands/sandbox/shields/status.ts

Repository: NVIDIA/NemoClaw

Length of output: 20815

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n## shields deferred-exit module\n'
cat -n src/lib/shields/deferred-exit.ts

Repository: NVIDIA/NemoClaw

Length of output: 1771

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n## shieldsStatus implementation\n'
sed -n '3315,3340p' src/lib/shields/index.ts

printf '\n## failShieldsCommand usage inside shields module\n'
rg -n -A2 -B2 '\bfailShieldsCommand\s*\(' src/lib/shields/index.ts

printf '\n## DeferredShieldsExit usage in shields module\n'
rg -n -A2 -B2 '\bDeferredShieldsExit\b|\bisDeferredShieldsExit\b' src/lib/shields/index.ts src/lib/shields/*.ts

Repository: NVIDIA/NemoClaw

Length of output: 10316

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n## withSandboxMutationLock implementation\n'
rg -n -A80 -B10 '\bfunction withSandboxMutationLock\b|\basync function withSandboxMutationLock\b' src/lib/state/mcp-lifecycle-lock.ts src/lib/state/*.ts src/lib/**/*.ts | sed -n '1,220p'

printf '\n## shields command tests around DeferredShieldsExit and locks\n'
rg -n -A6 -B6 'DeferredShieldsExit|process\.exit|setExitCode|withSandboxMutationLock\(' src/lib/shields/*.test.ts src/commands/sandbox/shields/*.ts | sed -n '1,260p'

Repository: NVIDIA/NemoClaw

Length of output: 196

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

cat -n src/lib/state/mcp-lifecycle-lock.ts

Repository: NVIDIA/NemoClaw

Length of output: 895

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

sed -n '1,260p' src/lib/state/mcp-lifecycle-lock-acquisition.ts

Repository: NVIDIA/NemoClaw

Length of output: 8937

---

Keep shields exits deferred through the CLI src/lib/shields/index.ts:779-783 — shieldsStatus() can reach this path while withSandboxMutationLock() is still held, so process.exit() here can skip lock cleanup. Re-throw the sentinel for CLI callers and let NemoClawCommand.catch set the exit code.

🤖 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/lib/shields/index.ts` around lines 767 - 776, Update failShieldsCommand
to always throw the DeferredShieldsExit sentinel instead of terminating the
process, preserving deferred exit handling for shieldsStatus paths reached while
withSandboxMutationLock is held. Keep NemoClawCommand.catch responsible for
translating the sentinel into the exit code, and retain the existing message and
status code.

Source: Path instructions

[Dongni-Yang]

Agreed this path is real, but it predates this PR and is deliberately out of scope here: this change moves the sentinel class to a leaf module and adds the missing CLI translation without touching completeDeferredShieldsExit or any transition semantics. The shieldsStatus in-lock process.exit strands the MCP lifecycle lock only until the stale-lock self-heal reclaims it, and rerouting status's exit path through the sentinel changes behavior for non-oclif callers — that deserves its own reviewed change rather than riding a targeted traceback fix for #7382. Happy to file it as a follow-up issue.

[coderabbitai]

@Dongni-Yang, agreed. This is a valid follow-up concern, but it should not expand this focused #7382 traceback fix or alter non-oclif behavior incidentally.

Would you like me to open a GitHub follow-up issue for the shieldsStatus() deferred-exit/lock-cleanup path, assigned to you?

---

✏️ Learnings added

Learnt from: Dongni-Yang
Repo: NVIDIA/NemoClaw PR: 7421
File: src/lib/shields/index.ts:0-0
Timestamp: 2026-07-23T04:21:12.671Z
Learning: In `src/lib/shields/index.ts`, `shieldsStatus()` can call `completeDeferredShieldsExit()` while a shields mutation lock is active. The resulting `process.exit()` can strand the lock until stale-lock self-healing reclaims it. Routing this through `NemoClawCommand.catch` would change behavior for non-oclif callers, so it requires a separately reviewed follow-up rather than being folded into targeted CLI traceback fixes.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

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 · 2 warnings · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 2 more warnings, 1 more suggestion.

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: credential-sanitization, security-posture

1 optional E2E recommendation

• shields-config

Workflow run details

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