no global nemoclaw doctor command -- bare invocation is parsed as a sandbox name #10212

Activity

1. hulynn

   added

   NV QABugs found by the NVIDIA QA TeamBugs found by the NVIDIA QA Team

   needs: triageAwaiting maintainer classificationAwaiting maintainer classification

   on Aug 25, 2026
2. hulynn

   added the

   Bug

   issue type on Aug 25, 2026
3. gaveezy

   self-assigned this

   on Aug 25, 2026
4. gaveezy commented on Aug 25, 2026

   

   gaveezy

   on Aug 25, 2026

   Contributor

   More actions

   picking up this
5. wscurran

   added

   area: cliCommand line interface, flags, terminal UX, or outputCommand line interface, flags, terminal UX, or output

   area: sandboxOpenShell sandbox lifecycle, runtime, config, or recoveryOpenShell sandbox lifecycle, runtime, config, or recovery

   platform: n1xAffects N1X hardware or workflowsAffects N1X hardware or workflows

   platform: wslAffects Windows Subsystem for LinuxAffects Windows Subsystem for Linux

   and removed

   needs: triageAwaiting maintainer classificationAwaiting maintainer classification

   on Aug 25, 2026
6. gaveezy commented on Aug 26, 2026

   

   gaveezy

   on Aug 26, 2026

   Contributor

   More actions

   Triage investigation

   I reproduced this report on commit 4f82ea594. src/lib/cli/public-dispatch.ts and src/lib/cli/argv-normalizer.ts are unchanged through 76dfee1a5, so the behavior below still applies to current main. I ran it with Node v22.23.2 on Linux x86_64 and zero registered sandboxes. The output matches the report exactly.

   Root cause

   nemoclaw doctor never reaches a diagnostic. The dispatcher classifies doctor as a sandbox name in three steps:

   1. src/lib/cli/argv-normalizer.ts:43 — no registered global command ID is named doctor, so the token falls through to the sandbox-first grammar.
   2. src/lib/cli/argv-normalizer.ts:49 — the argv has no second token, so action defaults to connect. The normalizer returns {sandboxName: "doctor", action: "connect"}.
   3. src/lib/cli/public-dispatch.ts:275 — the early-return guard does not fire, because connect is a registered sandbox action.

   src/lib/cli/public-dispatch.ts:282 then calls suggestGlobalCommand("doctor"). The nearest global command is deploy at edit distance 4. suggestCommand returns a candidate only at edit distance 2 or less, so no suggestion prints. src/lib/cli/public-dispatch.ts:290 prints the reported error.

   The defect is wider than doctor

   The repository registers 30 sandbox-scoped action tokens that no global command shares. I ran each one as a bare invocation with zero registered sandboxes. 27 print Sandbox '<token>' does not exist:

   channels, config, dashboard-url, destroy, doctor, download, exec, gateway, gateway-token, hosts-add, hosts-list, hosts-remove, logs, mcp, policy, policy-add, policy-explain, policy-get, policy-list, policy-remove, rebuild, recover, sessions, shields, skill, snapshot, upload

   Two more print Unknown command with an edit-distance suggestion:

   • share suggests nemoclaw start, which is an unrelated command.
   • agent suggests nemoclaw agents, which is a real global command.

   connect is the only sandbox action token with bare-invocation handling, in src/lib/cli/bare-connect-routing.ts (#6627).

   A global doctor is implementable

   collectHostChecks at src/lib/actions/sandbox/doctor.ts:187 already accepts SandboxEntry | null | undefined. When the caller passes null, it skips the portable check and calls resolveCurrentRuntimeProviderBundle().preflightDoctor.inspectHost(). The Host and Local services check groups need no sandbox.

   Two declarations would need to change:

   • DoctorReport.sandbox is a required string in src/lib/actions/sandbox/doctor-report.ts:21.
   • The oclif sandboxName argument is required: true in src/commands/sandbox/doctor.ts:27.

   Classification

   No documentation states a bare doctor form. docs/reference/commands.mdx documents nemoclaw <name> doctor at line 2249 only. The same file documents both nemoclaw <name> status at line 1996 and nemoclaw status at line 4244. This report requests new command surface. It is not a regression, and it is not a documentation mismatch.

   Proposed split

   Slice 1 — correct the diagnostic. Implemented in #10335, which is open as a draft. It adds no command surface. When a bare token names a registered sandbox action, the CLI reports the required grammar instead of a missing sandbox, and echoes the remaining arguments so the printed command is runnable. It covers the 27 tokens above and both suggestion cases. It follows getOpenShellCommandHint at src/lib/cli/public-dispatch.ts:431 (#3447), which already intercepts this argv shape.

   One reviewer-visible consequence: agent no longer suggests nemoclaw agents, because an exact sandbox-action match now wins over the edit-distance guess. #10335 records that precedence in a test.

   Slice 2 — add a global doctor command. This slice creates new command surface, so it needs a maintainer product decision under the product scope gate. PR #5540 (issue #754) is the precedent for the status scope pattern.

   Decision needed from maintainers

   Bare connect routes to the default sandbox. Bare status prints a global overview. This report asks for the status shape. The existing global nemoclaw debug command collects host diagnostics and accepts --sandbox NAME.

   Maintainers should confirm two points:

   1. Which behavior a global doctor provides.
   2. How a global doctor differs from nemoclaw debug.
7. wscurran

   assigned

   ericksoa

   on Sep 1, 2026
8. prekshivyas

   added a commit that references this issue on Sep 1, 2026

   fix(cli): report sandbox-first grammar for a bare sandbox action (#10335

   ...

   85e750e
9. cjagwani

   assigned

   cv

   and unassigned

   ericksoa

   and

   gaveezy

   on Sep 2, 2026
10. prekshivyas commented on Sep 3, 2026

    

    prekshivyas

    on Sep 3, 2026

    Collaborator

    More actions

    Product decision: Accept

    Reason: A user with no registered sandbox needs one command that reports host and NemoClaw gateway health. The current sandbox-scope hint from #10335 does not provide that diagnosis.

    Placement: Add nemoclaw doctor as a global command in the Troubleshooting group. Keep nemoclaw <name> doctor as the sandbox command.

    Accepted behavior:

    • The global command works with zero registered sandboxes.
    • It checks the CLI build, selected host runtime provider, OpenShell CLI, sandbox registry readability, and the resolved NemoClaw gateway lifecycle and reachability.
    • It is read-only. It does not recover the gateway or support --fix.
    • It does not run sandbox, inference, messaging, agent-version, permission, or agent-specific local-service checks.
    • Text output gives actionable hints and exits nonzero when a check fails.
    • --json returns a redacted schema-versioned global report with scope: "global" and no sandbox field.
    • Root help and the command reference show both the global and sandbox forms.
    • nemoclaw status remains the inventory view. nemoclaw debug remains the diagnostic-bundle collector. nemoclaw doctor reports actionable health checks.

    Accountable maintainer: @prekshivyas

    Validation plan: Add focused tests for public dispatch, zero-sandbox behavior, text and JSON output, failure exit status, read-only gateway inspection, registry-read failure, root help, command registry metadata, and documentation. Run the focused CLI tests, documentation build, and npm run validate:pr before publication.
11. github-actions

    assigned

    prekshivyas

    on Sep 3, 2026
12. ericksoa

    closed this as completedin #11012on Sep 4, 2026
13. ericksoa

    added a commit that references this issue on Sep 4, 2026

    fix(cli): add global host and gateway doctor (#11012)

    ...

    d99d1dc