fix(cli): report the sandbox agent in global list and status JSON

[laitingsheng]

Summary

nemoclaw list --json and the global nemoclaw status --json reported agent as null for an OpenClaw sandbox, while nemoclaw list text and nemoclaw <name> status --json reported openclaw. The registry stores null for a sandbox with no explicit agent, and only the text and sandbox-scoped surfaces resolved that marker. Both global JSON surfaces now resolve it the same way, so automation reading either surface gets the agent instead of null.

Related Issue

Fixes #8694

Changes

• Add resolveDisplayAgent in src/lib/inventory/index.ts as the one place every inventory surface resolves the stored agent marker: null or absent becomes openclaw, and a row recovered from the live OpenShell gateway stays unknown. A direct change at each surface is insufficient because the three current consumers (buildSandboxInventoryRow, buildStatusSandboxRow, and renderSandboxInventoryText) drifted apart while each held its own default. test/sandbox-agent-surface-parity.test.ts protects the shared contract.
• Narrow SandboxInventoryRow.agent and StatusSandboxRow.agent from string | null to string.
• Replace the unreachable safeStatusString(...) ?? "openclaw" fallback in buildStatusSandboxRow with a direct redactFull call.
• Add test/sandbox-agent-surface-parity.test.ts, which runs the CLI against a registry entry with agent: null and asserts that list --json, global status --json, <name> status --json, and list text all report openclaw.
• Document the agent value contract for nemoclaw list, nemoclaw status, and nemoclaw <name> status in docs/reference/commands.mdx.

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/reference/commands.mdx
• Agent: Codex Desktop

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 — npm exec -- vitest run --project cli src/lib/inventory/index.test.ts (48/48) and npm exec -- vitest run --project integration test/sandbox-agent-surface-parity.test.ts (1/1) passed at the latest PR commit.
• Applicable broad gate passed — not applicable to this focused inventory contract and parity-test change; targeted CLI/integration suites and required CI are the proportionate evidence.
• 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) — strict docs validation completed with 0 errors and 2 existing repository warnings.
• 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

  • Sandbox listings and status output now display each sandbox’s agent label.
  • Missing agent labels default to openclaw; recovered live-gateway sandboxes display unknown.
  • Agent labels are consistently shown in both text and JSON output.

• Documentation

  • Updated the command reference to document agent labels and their fallback values.

• Tests

  • Added coverage verifying agent reporting across sandbox list and status commands.

[coderabbitai]

📝 Walkthrough

Walkthrough

Inventory and status rows now expose string-valued agents. Missing registry agents default to openclaw; gateway-recovered entries use unknown. CLI documentation and parity tests cover list and status output.

Changes

Sandbox agent reporting

Layer / File(s)	Summary
Agent contract and resolution src/lib/inventory/index.ts	Inventory and status rows now require string-valued agents. resolveDisplayAgent preserves explicit agents, uses unknown for gateway-recovered entries, and defaults other missing agents to openclaw.
CLI surface integration src/lib/inventory/index.ts, test/sandbox-agent-surface-parity.test.ts, docs/reference/commands.mdx	List and status output use resolved agent values. The parity test checks JSON and text surfaces. The command reference documents fallback behavior and global status limitations.

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

Possibly related PRs

• NVIDIA/NemoClaw#8735: Changes recovery handling for stale gateway sandboxes, which relates to the unknown agent value for gateway-recovered entries.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 37.50% 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
Linked Issues check	✅ Passed	The changes resolve issue #8694 by standardizing agent values across global JSON, scoped JSON, and text surfaces, with parity tests.
Out of Scope Changes check	✅ Passed	The code, documentation, and parity tests directly support the linked issue and stated pull request objectives.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: reporting the sandbox agent in global list and status JSON output.

✨ 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/inventory-json-agent-parity

---

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

[github-actions]

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 10c1526 in the fix/inventory-json-a... branch remains at 96%, unchanged from commit 6df126c in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 10c1526 in the fix/inventory-json-a... branch remains at 82%, unchanged from commit 6df126c in the main branch.

Show a code coverage summary of the most impacted files.

File	main 6df126c	fix/inventory-json-a... 10c1526	+/-
src/lib/state/g...way-registry.ts	98%	97%	-1%
src/lib/onboard...-transaction.ts	94%	94%	0%
src/lib/state/o...config-merge.ts	92%	92%	0%
src/lib/inventory/index.ts	90%	90%	0%
src/lib/onboard...ad/authority.ts	95%	95%	0%
src/lib/sandbox...rce-identity.ts	86%	86%	0%
src/lib/state/r...ime-snapshot.ts	100%	100%	0%
src/lib/actions...aged-profile.ts	84%	88%	+4%
src/lib/actions...er-lifecycle.ts	85%	94%	+9%

---

_{Updated August 11, 2026 07:01 UTC}

[coderabbitai]

🧹 Nitpick comments (1)

test/sandbox-agent-surface-parity.test.ts (1)

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

Add CLI-level gateway-recovery coverage.

Existing tests cover inventory construction and text rendering, but no test drives nemoclaw list --json and nemoclaw list with recoveredFromGateway: true. Assert agent: "unknown" in JSON and agent: unknown in text.

🤖 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/sandbox-agent-surface-parity.test.ts` around lines 106 - 120, Add
CLI-level coverage alongside the existing parity test that exercises both
`runCliJson(["list", "--json"])` and `runCli(["list"])` when gateway recovery
produces `recoveredFromGateway: true`. Assert the JSON result reports `agent` as
`"unknown"` and the combined text output contains `agent: unknown`, reusing the
existing test setup and helpers.

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.

Nitpick comments:
In `@test/sandbox-agent-surface-parity.test.ts`:
- Around line 106-120: Add CLI-level coverage alongside the existing parity test
that exercises both `runCliJson(["list", "--json"])` and `runCli(["list"])` when
gateway recovery produces `recoveredFromGateway: true`. Assert the JSON result
reports `agent` as `"unknown"` and the combined text output contains `agent:
unknown`, reusing the existing test setup and helpers.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9c05522d-3abb-44c9-9d34-fc6ae28b1187

📥 Commits

Reviewing files that changed from the base of the PR and between 3ac3a77 and 2bd9dbd.

📒 Files selected for processing (3)

• docs/reference/commands.mdx
• src/lib/inventory/index.ts
• test/sandbox-agent-surface-parity.test.ts

[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): Failed after a partial review · low confidence · 0 blockers · 1 warning · 1 suggestion

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

1 semantic terminology decision

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

• established — agent at docs/reference/commands.mdx:954: Keep agent for the reported sandbox agent runtime.

E2E guidance

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

Recommended E2E: None

Workflow run details

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

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[prekshivyas]

Reviewed the latest PR commit 10c1526 against base SHA 6df126c. Focused inventory/parity tests, strict docs validation, required CI, protected E2E, independent docs review, CodeRabbit, contributor compliance, and the primary advisor lane are green. The trusted advisor publisher reports merge_as_is with zero findings.