Skip to content

fix(cli): align shields status and logs tail UX#3866

Merged
ericksoa merged 1 commit into
NVIDIA:mainfrom
yimoj:fix/3702-shields-logs-ux
May 22, 2026
Merged

fix(cli): align shields status and logs tail UX#3866
ericksoa merged 1 commit into
NVIDIA:mainfrom
yimoj:fix/3702-shields-logs-ux

Conversation

@yimoj

@yimoj yimoj commented May 20, 2026

Copy link
Copy Markdown
Contributor

Summary

Aligns status and doctor shields wording with the canonical shields state so fresh mutable sandboxes report as not configured instead of down. Clarifies NemoClaw versus OpenShell log tail semantics and locks the combined logs --follow --tail <lines> argv behavior with tests.

Related Issue

Fixes #3702

Changes

  • Added getShieldsPosture() for canonical shields state labels and reused it in status, doctor, and shields status.
  • Added focused CLI regressions for fresh shields status/doctor output and logs --follow --tail <lines> routing.
  • Updated command docs to distinguish NemoClaw --tail <lines> from OpenShell --tail follow behavior.

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)

Verification

  • npx prek run --all-files passes
  • npm test passes
  • Tests added or updated for new or changed behavior
  • No secrets, API keys, or credentials committed
  • Docs updated for user-facing behavior changes
  • make 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)

Focused verification run locally:

  • npm run build:cli
  • npx vitest run src/lib/domain/sandbox/logs.test.ts src/lib/shields/index.test.ts test/cli.test.ts -t "sandbox logs helpers|shields — unit logic|doctor reports fresh shields state|status reports fresh shields state|passes --tail line count|passes -n line count|passes --follow --tail line count|maps --follow to OpenShell live log streaming|passes plain logs through without the tail flag"
  • Isolated real CLI probe under HOME=/tmp/nemoclaw-fix-3702-home / NEMOCLAW_HOME=/tmp/nemoclaw-fix-3702-home/.nemoclaw, including timeout 30s node bin/nemoclaw.js fix3702-alpha logs --follow --tail 7
  • npm run typecheck:cli
  • cd nemoclaw && npm run build
  • make docs (Fern reported 0 errors and 2 hidden warnings)
  • codex review -c sandbox_mode="danger-full-access" --uncommitted

npx prek run --all-files was attempted. Static/docs/plugin stages passed, but the full CLI coverage hook failed after about 13.5 minutes in unrelated broad-suite paths: multiple existing test/cli.test.ts timeouts, test/fetch-guard-patch-regression.test.ts, and test/sandbox-connect-inference.test.ts. Scoped regressions and typecheck/build/docs checks above passed after that.


Signed-off-by: Yimo Jiang yimoj@nvidia.com

Summary by CodeRabbit

Release Notes

  • Documentation

    • Clarified openshell logs command flag semantics and usage in CLI guides with explicit examples and NemoClaw comparison.
  • Bug Fixes

    • Improved shields/permissions status reporting with richer, posture-aware status information.
    • Enhanced sandbox doctor checks and status display with clearer shield and permission state messaging.

Review Change Stack

Signed-off-by: Yimo Jiang <yimoj@nvidia.com>
@yimoj yimoj self-assigned this May 20, 2026
@coderabbitai

coderabbitai Bot commented May 20, 2026

Copy link
Copy Markdown
Contributor

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: 38283714-cb3d-44a4-b9e5-3e0c8f73ae16

📥 Commits

Reviewing files that changed from the base of the PR and between 11b1937 and f1b0b40.

📒 Files selected for processing (7)
  • docs/reference/cli-selection-guide.mdx
  • docs/reference/commands.mdx
  • src/lib/actions/sandbox/doctor.ts
  • src/lib/actions/sandbox/status.ts
  • src/lib/shields/index.test.ts
  • src/lib/shields/index.ts
  • test/cli.test.ts

📝 Walkthrough

Walkthrough

This PR unifies shields status terminology across CLI commands by introducing a ShieldsPosture abstraction with canonical wording, and clarifies documentation for the semantic mismatch between NemoClaw's and OpenShell's --tail flag usage.

Changes

Shields Posture Model & Terminology Unification

Layer / File(s) Summary
Shields posture types and helpers
src/lib/shields/index.ts
Adds ShieldsPostureMode type with error state, defines LoadedShieldsState and ShieldsPosture interfaces carrying derived mode/detail/statusText/locked/mutable flags, and centralizes mode-to-description mapping in describeShieldsMode helper; exports getShieldsPosture for callers.
Shields posture computation and shieldsStatus refactor
src/lib/shields/index.ts
Implements getShieldsPosture function to load and derive canonical posture state, updates recoverExpiredAutoRestoreGate return type, and refactors shieldsStatus command to switch on posture.mode instead of raw state, using standardized statusText labels for each mode.
Status and doctor command integration
src/lib/actions/sandbox/status.ts, src/lib/actions/sandbox/doctor.ts
Updates showSandboxStatus Permissions output and runSandboxDoctor Shields check to use getShieldsPosture, printing posture-aware details conditionally and mapping modes to appropriate status levels (ok/warn/info) with mode-specific hints.
Shields posture unit and integration tests
src/lib/shields/index.test.ts, test/cli.test.ts
Adds unit test validating getShieldsPosture returns correct mode/detail/statusText for default mutable, locked, and temporarily unlocked scenarios; adds doctor, status, and logs CLI integration tests verifying posture-based output rendering and flag handling.

CLI Documentation for --tail Flag Semantics

Layer / File(s) Summary
CLI selection guide and commands reference
docs/reference/cli-selection-guide.mdx, docs/reference/commands.mdx
Updates cli-selection-guide with explicit -n 200 --tail for openshell logs and adds explanatory note contrasting NemoClaw's line-count --tail with OpenShell's boolean --tail (stream) and -n <lines> (count); updates commands.mdx with clarification of the semantic difference.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

Possibly related PRs

  • NVIDIA/NemoClaw#3204: Overlaps in shields state/posture handling in src/lib/shields/index.ts, particularly around temporarily_unlocked state and recoverExpiredAutoRestoreGate behavior, as both PRs modify the same status computation paths.

Suggested labels

fix, NemoClaw CLI, documentation, status: rfr, v0.0.46

Suggested reviewers

  • ericksoa
  • cv
  • jyaunches

Poem

A rabbit hops through shields so clear,
No more confusion, terminology sincere!
Where mutable_default states the truth,
And --tail flags sing in gentle youth.
From status to doctor, one voice rings,
A unified posture—what clarity brings! 🐰✨

🚥 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 'fix(cli): align shields status and logs tail UX' accurately and concisely summarizes the main changes: aligning shields terminology and clarifying logs --tail behavior across commands.
Linked Issues check ✅ Passed The PR addresses both objectives from #3702: (E1) updated docs to clarify NemoClaw vs OpenShell --tail semantics; (E2) implemented canonical shields status via getShieldsPosture() for consistent terminology across status, doctor, and shields status commands.
Out of Scope Changes check ✅ Passed All changes are scoped to the linked issue: documentation updates for --tail semantics, new getShieldsPosture() function, updates to status/doctor/shields-status commands, CLI tests for changed behavior, and test coverage for the new posture model.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.


Comment @coderabbitai help to get the list of available commands and usage tips.

@yimoj yimoj added the v0.0.48 Release target label May 20, 2026
@wscurran

Copy link
Copy Markdown
Contributor

@ericksoa ericksoa merged commit 74c0246 into NVIDIA:main May 22, 2026
32 checks passed
miyoungc added a commit that referenced this pull request May 22, 2026
Audit found the v0.0.49 release notes promised behaviors that did not ship
or were never implemented. Realign to the actual code on main.

- Drop the EXDEV runtime-deps claim: #3820 was reverted by #4051 in this
  release window, so the behavior is not present.
- Drop the "skip broad permission repair" claim: no corresponding commit
  in v0.0.48..v0.0.49.
- Rewrite the gateway probe classifier list in release-notes.mdx and
  commands.mdx to match the real states emitted by
  src/lib/status-command-deps.ts (named gateway unreachable / present
  but not Connected / pointing at a different name / not configured).
  The previous "non-JSON health response" example did not exist in code.
- Expand the channel-removal bullet to describe #4001's user-visible
  teardown (durable QR-paired state wipe, abort-on-failure, config.json
  re-sync) in addition to the existing #4013 sync.
- Add bullets for user-visible PRs that were merged in the release
  window but missing from the notes: #3854 (restricted dmesg in debug
  output), #3866 (shields status and logs --tail UX), #3984 (Hermes
  messaging policy scoping), and #4011 (Docker group security note).

Regenerated nemoclaw-user-overview and nemoclaw-user-reference skills
from the updated docs via scripts/docs-to-skills.py.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
cv pushed a commit that referenced this pull request May 22, 2026
## Summary
Refreshes the NemoClaw docs for the v0.0.49 hardening release, including
release notes, command reference updates, troubleshooting guidance,
version metadata, and regenerated user skills.

## Changes
- #3796, #3854, #3863, #3866, #3984, #4001, #4011, #4013, #4020, #4022,
#4023, #4060, #4062 -> `docs/about/release-notes.mdx`: Adds the v0.0.49
hardening release summary covering gateway reliability,
status/doctor/shields and debug UX, OpenClaw compatibility, messaging
channel teardown, Hermes policy scoping, snapshots, source installs and
Docker group security note, GPU preflight, CLI usage, E2E, and CI
improvements.
- #3796 -> `docs/manage-sandboxes/backup-restore.mdx` and
`docs/reference/commands.mdx`: Documents `snapshot restore --to`
overwrite protection and the `--force` opt-in.
- #3863, #4013, #4020, #4023 -> `docs/reference/commands.mdx`: Documents
missing channel argument usage, sandbox-scoped custom preset matching,
session policy preset sync, and gateway failure classification (uses the
real probe states from `src/lib/status-command-deps.ts`).
- #4022, #4060, #4062 -> `docs/reference/troubleshooting.mdx`: Adds
guidance for gateway-down `connect`, source checkout OpenShell
bootstrapping, WDDM placeholder GPU names, and Jetson sandbox GPU
passthrough.
- Release prep -> `docs/project.json`, `docs/versions1.json`,
`.agents/skills/nemoclaw-user-*`: Bumps docs metadata to 0.0.49 and
refreshes generated user skills from the Fern docs.

## Type of Change
- [ ] Code change (feature, bug fix, or refactor)
- [ ] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [x] Doc only (includes code sample changes)

## Verification
- [x] `npx prek run --all-files` passes
- [ ] `npm test` passes
- [ ] Tests added or updated for new or changed behavior
- [x] No secrets, API keys, or credentials committed
- [x] Docs updated for user-facing behavior changes
- [ ] `make docs` builds without warnings (doc changes only)
- [x] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

\`make docs\` was attempted locally but did not complete because \`npm\`
returned \`403 Forbidden\` while fetching \`fern-api\` from
\`registry.npmjs.org\` in the sandboxed environment.

---
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Released v0.0.49 with reliability and compatibility improvements
including faster gateway failure diagnostics and safer snapshot restore
behavior
* Enhanced snapshot restore documentation with `--to` cloning and
`--force` overwrite requirements
* Expanded troubleshooting guides for source installs, GPU setup, and
gateway recovery
* Clarified Docker group access requirements and improved CLI command
reference

* **Chores**
  * Version bumped to 0.0.49

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NemoClaw/pull/4078?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@wscurran wscurran added area: cli Command line interface, flags, terminal UX, or output bug-fix PR fixes a bug or regression and removed NemoClaw CLI labels Jun 3, 2026
@wscurran wscurran removed the fix label Jun 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: cli Command line interface, flags, terminal UX, or output bug-fix PR fixes a bug or regression v0.0.49 Release target

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[All Platforms][UX] --tail flag semantic mismatch + shields status terminology drift

4 participants