fix(exec): reject multi-line exec args with recovery guidance (#5980)

docs/reference/commands-nemohermes.mdx

@@ -470,6 +470,12 @@ Everything after `--` is forwarded verbatim to the sandbox command, including fl
 
 The exit code is the remote command's exit code.
 
+The OpenShell exec endpoint rejects any command argument (the values after `--`) that contains a newline or carriage return, so multi-line commands such as a `bash` heredoc cannot be passed through `exec`.
+NemoClaw detects this before dispatch, names the offending argument position, and exits with status `2` instead of surfacing the lower-level OpenShell `InvalidArgument` error.
+Join the statements with semicolons (`nemohermes <name> exec -- bash -lc "cmd1; cmd2"`).
+Pipe the script into the sandbox shell over stdin (`printf 'cmd1\ncmd2\n' | nemohermes <name> exec -- bash`).
+Or write the script to a file in the sandbox and run it (`nemohermes <name> exec -- bash <script-path>`).
+
 | Flag | Description |
 |------|-------------|
 | `--workdir <dir>` | Working directory inside the sandbox. The directory is checked before the command runs; if it does not exist, NemoClaw reports `error: --workdir: <dir> does not exist inside the sandbox` and exits with status `1` without invoking the inner command. |

docs/reference/commands.mdx

@@ -590,6 +590,12 @@ The exit code is the remote command's exit code.
 
 </AgentOnly>
 
+The OpenShell exec endpoint rejects any command argument (the values after `--`) that contains a newline or carriage return, so multi-line commands such as a `bash` heredoc cannot be passed through `exec`.
+NemoClaw detects this before dispatch, names the offending argument position, and exits with status `2` instead of surfacing the lower-level OpenShell `InvalidArgument` error.
+Join the statements with semicolons (`$$nemoclaw <name> exec -- bash -lc "cmd1; cmd2"`).
+Pipe the script into the sandbox shell over stdin (`printf 'cmd1\ncmd2\n' | $$nemoclaw <name> exec -- bash`).
+Or write the script to a file in the sandbox and run it (`$$nemoclaw <name> exec -- bash <script-path>`).
+
 | Flag | Description |
 |------|-------------|
 | `--workdir <dir>` | Working directory inside the sandbox. The directory is checked before the command runs; if it does not exist, NemoClaw reports `error: --workdir: <dir> does not exist inside the sandbox` and exits with status `1` without invoking the inner command. |

src/commands/sandbox/exec.test.ts

@@ -41,6 +41,43 @@ describe("SandboxExecCommand oclif parse path", () => {
     });
   });
 
+  it("forwards a multi-line heredoc command verbatim to the action guard (#5980)", async () => {
+    // The command layer forwards argv unchanged; execSandbox() applies the
+    // newline guard (exit 2 before dispatch), which is asserted directly in the
+    // action test. Here we pin that the heredoc reaches the action intact.
+    const heredoc = "cat <<EOF\nline1\nline2\nEOF";
+    await SandboxExecCommand.run(["alpha", "--", "bash", "-lc", heredoc], rootDir);
+    expect(execSandboxMock).toHaveBeenCalledWith("alpha", ["bash", "-lc", heredoc], {
+      workdir: undefined,
+      tty: null,
+      timeoutSeconds: undefined,
+    });
+  });
+
+  it("forwards the semicolon workaround to dispatch (#5980)", async () => {
+    // Mirrors the action-layer "forwards the semicolon workaround to dispatch"
+    // test: the single-line semicolon-joined command carries no newline, so the
+    // command layer hands it to execSandbox() unchanged, which then dispatches.
+    await SandboxExecCommand.run(["alpha", "--", "bash", "-lc", "echo line1; echo line2"], rootDir);
+    expect(execSandboxMock).toHaveBeenCalledWith(
+      "alpha",
+      ["bash", "-lc", "echo line1; echo line2"],
+      { workdir: undefined, tty: null, timeoutSeconds: undefined },
+    );
+  });
+
+  it("preserves --workdir and forwards a single-line command unchanged (#5980)", async () => {
+    await SandboxExecCommand.run(
+      ["alpha", "--workdir", "/sandbox", "--", "bash", "-lc", "echo line1; echo line2"],
+      rootDir,
+    );
+    expect(execSandboxMock).toHaveBeenCalledWith(
+      "alpha",
+      ["bash", "-lc", "echo line1; echo line2"],
+      { workdir: "/sandbox", tty: null, timeoutSeconds: undefined },
+    );
+  });
+
   it("parses --tty / --no-tty and --timeout into typed options", async () => {
     await SandboxExecCommand.run(["alpha", "--tty", "--timeout", "30", "--", "hostname"], rootDir);
     expect(execSandboxMock).toHaveBeenCalledWith("alpha", ["hostname"], {