fix(plugin): route registration banner to stderr (NVIDIA#6480)

<!-- markdownlint-disable MD041 -->
## Summary
Routes the in-sandbox NemoClaw registration banner to `stderr` so
non-JSON agent output on `stdout` remains machine-readable.
This is a current-main, GitHub-verified replacement for NVIDIA#5674 that
preserves the contributor's original authorship.

## Related Issue
Fixes NVIDIA#5654.

## Changes
- Write the plugin registration banner directly to `stderr` instead of
plugin info logs.
- Cover banner routing, live model rendering, mock restoration, and the
non-JSON passthrough stream boundary.
- Document the agent command's stdout/stderr contract.

## Type of Change

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

## Quality Gates
<!-- Check exactly one tests line and one docs line. Check other lines
when applicable. Add every requested justification or approval
reference. -->
- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [x] 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:

## Verification
<!-- Check each applicable item only when supported by the requested
evidence. Run targeted tests once per relevant change set and rerun
after later edits or hook autofixes that can affect the tested behavior.
Do not rerun hook-covered checks. -->
- [x] PR description includes the DCO sign-off declaration and every
commit appears as `Verified` in GitHub
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run check:diff` passed when hooks were skipped or unavailable
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — command/result or justification: `npm
--prefix nemoclaw test -- src/register.test.ts` passed 24/24; `npx
vitest run --project cli
src/lib/actions/sandbox/agent/passthrough.test.ts` passed 38/38; plugin
and CLI builds passed.
- [ ] Applicable broad gate passed — `npm test` for broad
runtime/test-harness changes; `npm run check` for repo-wide
validation/coverage changes — command/result:
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run 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)

`npm run docs` passed with zero errors and two pre-existing Fern
warnings.

---
<!-- DCO sign-off is required in this PR description, and every commit
must appear as Verified in GitHub. Run: git config user.name && git
config user.email -->
Signed-off-by: Carlos Villela <cvillela@nvidia.com>


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

* **Bug Fixes**
* Updated agent startup so the NemoClaw registration banner is emitted
to standard error, avoiding interference with non-JSON agent replies on
standard output.
* **Documentation**
* Refreshed the command reference to clarify where the banner appears
during non-JSON runs.
* **Tests**
* Revised banner-related tests to capture and assert standard error
output, and added coverage to ensure standard output remains clean for
non-JSON replies.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: WilliamK112 <164879897+WilliamK112@users.noreply.github.com>
Signed-off-by: Carlos Villela <cvillela@nvidia.com>
Co-authored-by: WilliamK112 <164879897+WilliamK112@users.noreply.github.com>

Author: cv

docs/reference/commands.mdx

@@ -869,6 +869,7 @@ $$nemoclaw dcode-sandbox agent -n "Summarize this repository"
 When post-command permission cleanup succeeds, the wrapper inherits the remote command's exit code so host-side pipelines can branch on it.
 If cleanup fails closed, the wrapper prints the command and cleanup statuses to `stderr` and returns the cleanup failure.
 For normal turns, streaming forwards whatever the in-sandbox agent command emits on `stdout`; the wrapper adds no buffering.
+The in-sandbox NemoClaw plugin writes its registration banner to `stderr`, so the banner does not prefix the agent reply on `stdout` in non-JSON mode.
 When the top-level OpenClaw `--json` output flag is present, the wrapper uses a captured no-TTY path with a `64 MiB` buffer so `stdout` stays parseable JSON.
 Raw `stderr` is forwarded, and failed-tool or untrusted-child provenance found in the stdout JSON is appended to `stderr`.
 Literal `--json` values consumed by flags such as `-m` or `--reply-channel`, or arguments after `--`, stay on the normal passthrough path.

nemoclaw/src/index.ts

@@ -437,9 +437,9 @@ export default function register(api: OpenClawPluginApi): void {
     "  Slash:     /nemoclaw",
   ];
 
-  api.logger.info("");
+  process.stderr.write("\n");
   for (const line of renderBox(bannerLines)) {
-    api.logger.info(line);
+    process.stderr.write(`${line}\n`);
   }
-  api.logger.info("");
+  process.stderr.write("\n");
 }

nemoclaw/src/register.test.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawPluginApi } from "./index.js";
 
 vi.mock("node:fs", async (importOriginal) => {
@@ -32,6 +32,17 @@ const mockedReadFileSync = vi.mocked(readFileSync);
 const mockedLoadOnboardConfig = vi.mocked(loadOnboardConfig);
 const originalReadFileSync = (await vi.importActual<typeof import("node:fs")>("node:fs"))
   .readFileSync;
+let stderrWrite: ReturnType<typeof vi.spyOn>;
+
+function mockStderrWrite(): void {
+  stderrWrite = vi
+    .spyOn(process.stderr, "write")
+    .mockImplementation((() => true) as typeof process.stderr.write);
+}
+
+function stderrOutput(): string {
+  return stderrWrite.mock.calls.map(([chunk]) => String(chunk)).join("");
+}
 
 function mockMissingOpenClawConfig(): void {
   mockedReadFileSync.mockReset();
@@ -64,13 +75,18 @@ function createMockApi(): OpenClawPluginApi {
   };
 }
 
-describe("plugin registration", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockMissingOpenClawConfig();
-    mockedLoadOnboardConfig.mockReturnValue(null);
-  });
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockStderrWrite();
+  mockMissingOpenClawConfig();
+  mockedLoadOnboardConfig.mockReturnValue(null);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
 
+describe("plugin registration", () => {
   it("registers a slash command", () => {
     const api = createMockApi();
     register(api);
@@ -140,8 +156,15 @@ describe("plugin registration", () => {
     expect(providerArg.models?.chat).toEqual([
       expect.objectContaining({ id: "inference/nvidia/live-model", label: "nvidia/live-model" }),
     ]);
-    const logLines = vi.mocked(api.logger.info).mock.calls.map(([message]) => message);
-    expect(logLines.some((line) => line.includes("Model:     nvidia/live-model"))).toBe(true);
+    expect(stderrOutput()).toContain("Model:     nvidia/live-model");
+  });
+
+  it("writes the registration banner to stderr instead of plugin info logs", () => {
+    const api = createMockApi();
+    register(api);
+
+    expect(stderrOutput()).toContain("NemoClaw registered");
+    expect(api.logger.info).not.toHaveBeenCalled();
   });
 
   it("falls back to onboard config when openclaw.json has no primary model", () => {
@@ -178,22 +201,14 @@ describe("plugin registration", () => {
       expect.objectContaining({ id: "nvidia/nemotron-3-nano-30b-a3b" }),
     ]);
 
-    const logLines = vi.mocked(api.logger.info).mock.calls.map(([message]) => message);
-    expect(logLines.some((line) => line.includes("Endpoint:  build.nvidia.com"))).toBe(true);
-    expect(logLines.some((line) => line.includes("Provider:  NVIDIA Endpoints"))).toBe(true);
-    expect(
-      logLines.some((line) => line.includes("Model:     nvidia/nemotron-3-super-120b-a12b")),
-    ).toBe(true);
+    const stderr = stderrOutput();
+    expect(stderr).toContain("Endpoint:  build.nvidia.com");
+    expect(stderr).toContain("Provider:  NVIDIA Endpoints");
+    expect(stderr).toContain("Model:     nvidia/nemotron-3-super-120b-a12b");
   });
 });
 
 describe("before_tool_call secret scanner hook (#1233)", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockMissingOpenClawConfig();
-    mockedLoadOnboardConfig.mockReturnValue(null);
-  });
-
   function getHookHandler(api: OpenClawPluginApi) {
     register(api);
     const onCalls = vi.mocked(api.on).mock.calls;

src/lib/actions/sandbox/agent/passthrough.test.ts

@@ -37,9 +37,36 @@ vi.mock("../../../agent/defs", () => ({
 vi.mock("../../../shields/audit", () => ({
   readRecentShieldsAutoRestore: vi.fn(() => ({ kind: "none" })),
 }));
+vi.mock("../../../../../nemoclaw/src/onboard/config.js", () => ({
+  loadOnboardConfig: vi.fn(() => null),
+  describeOnboardEndpoint: vi.fn(() => "build.nvidia.com"),
+  describeOnboardProvider: vi.fn(() => "NVIDIA Endpoint API"),
+}));
 
+import registerPlugin, { type OpenClawPluginApi } from "../../../../../nemoclaw/src/index";
 import { type AgentPassthroughDeps, runAgentPassthrough } from "./passthrough";
 
+function createPluginApi(): OpenClawPluginApi {
+  return {
+    id: "nemoclaw",
+    name: "NemoClaw",
+    version: "0.1.0",
+    config: {},
+    pluginConfig: {},
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    },
+    registerCommand: vi.fn(),
+    registerProvider: vi.fn(),
+    registerService: vi.fn(),
+    resolvePath: vi.fn((value: string) => value),
+    on: vi.fn(),
+  };
+}
+
 describe("runAgentPassthrough", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -86,6 +113,39 @@ describe("runAgentPassthrough", () => {
     );
   });
 
+  it("keeps a non-JSON agent reply isolated from the plugin banner (#5654)", async () => {
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+    const stdoutWrite = vi.spyOn(process.stdout, "write").mockImplementation(((chunk) => {
+      stdout.push(String(chunk));
+      return true;
+    }) as typeof process.stdout.write);
+    const stderrWrite = vi.spyOn(process.stderr, "write").mockImplementation(((chunk) => {
+      stderr.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write);
+    const exec = vi.fn(async () => {
+      registerPlugin(createPluginApi());
+      process.stdout.write("ack\n");
+    });
+    getSandboxMock.mockReturnValueOnce({ agent: "openclaw" });
+
+    try {
+      await runAgentPassthrough(
+        "alpha",
+        { extraArgs: ["--agent", "main", "-m", "ping"] },
+        { exec, getRecentShieldsAutoRestore: () => ({ kind: "none" }) },
+      );
+    } finally {
+      stdoutWrite.mockRestore();
+      stderrWrite.mockRestore();
+    }
+
+    expect(stdout.join("")).toBe("ack\n");
+    expect(stdout.join("")).not.toContain("NemoClaw registered");
+    expect(stderr.join("")).toContain("NemoClaw registered");
+  });
+
   it("uses the captured JSON path for `openclaw agent --json` so provenance can be emitted on stderr", async () => {
     const execJson = vi.fn(() => {
       throw new Error("__exit:0");