fix(cli): close non-terminal sandbox exec stdin by default

[HwangJohn]

Summary

Fixes sandbox exec hangs caused by forwarding a live non-terminal stdin that never reaches EOF. NemoClaw now inherits stdin by default only for terminals, closes non-terminal or unavailable stdin, and keeps intentional pipes available through --stdin.

Related Issue

Fixes #6319

Changes

• Merge current main without rewriting the contributor's commits or credit.
• Add public --stdin / --no-stdin controls, with explicit flags taking precedence over TTY detection.
• Thread stdin?: boolean through sandbox exec and select inherited versus ignored stdin in the async production spawner.
• Keep the stdio policy and its focused tests in companion modules so the existing exec action/test files stay within growth limits.
• Preserve signal forwarding, remote exit codes, cleanup, workdir and multiline guards, and denial-adjacent policy hints.
• Update NemoClaw and NemoHermes command references so piped scripts opt in with --stdin.
• Add parser, default-selection, production-stdio, multiline-guidance, signal, cleanup, exit-code, and policy-hint coverage.

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: fresh maintainer review requested on the new semantics; the prior approval predates this head and does not satisfy this gate.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub — GitHub reports all 10 PR commits verified at d73686641e828025789dedf581099b9f23e4b988.
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable — npm run check:diff passed at d73686641e828025789dedf581099b9f23e4b988.
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — the sandbox-exec command/action/policy/cleanup/stdio plus runtime-environment matrix passed 11 files / 160 tests; npm run build:cli, CLI typecheck, and npm run docs:strict also passed.
• Applicable broad gate passed — exact-head required CI run 28829324545 passed (including the successful same-head retry of one unrelated timing flake), and advisor-selected E2E run 28829674160 passed 3/3 jobs.
• Quality Gates section completed with required justifications or waivers — fresh sensitive-path review is pending.
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — npm run docs:strict found 0 errors and two pre-existing hidden Fern warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

The exact-head isolated OpenShell 0.0.72 proof 2026-07-06T23-01-11-471Z-pid-7719 passed: a held-open non-TTY FIFO returned promptly by default, /dev/null reached EOF, --stdin forwarded a finite two-line script, remote exit status 37 propagated, and a parent-only SIGTERM produced NemoClaw exit 143. OpenShell 0.0.72 has no remote exec cancellation operation, so the harness recorded its pre-existing detached-command behavior separately and removed the uniquely tagged process after identity verification.

Both exact-head PR advisors (28829423941) returned merge_as_is with no blocker or warning. The E2E advisor (28829422926) selected sessions-agents-cli, sandbox-operations, and shields-config; all three passed. Fresh human approval remains required because the existing approval predates this head and its stdin semantics.

---

Signed-off-by: HwangJohn angelic805@gmail.com
Signed-off-by: Aaron Erickson aerickson@nvidia.com

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new --stdin/--no-stdin CLI flag, threads a stdin?: boolean option through SandboxExecOptions, maps it to spawnSync stdio via buildSandboxExecStdio, updates exec command parsing and tests, and updates reference docs including nemohermes entries.

Changes

Sandbox stdin control feature

Layer / File(s)	Summary
Type and CLI flag definition src/lib/actions/sandbox/exec.ts, src/commands/sandbox/exec.ts	SandboxExecOptions gains stdin?: boolean. CLI help and examples updated; adds --stdin/--no-stdin with allowNo and explanatory examples.
CLI integration and parsing tests src/commands/sandbox/exec.ts, src/commands/sandbox/exec.test.ts	Exec command computes stdin via exported shouldInheritSandboxExecStdin and passes it into execSandbox. Tests updated to assert stdin in calls, add --stdin, --no-stdin, default inheritance cases, and unit tests for the helper.
Action-level stdio builder and tests src/lib/actions/sandbox/exec.ts, src/lib/actions/sandbox/exec.test.ts	Add buildSandboxExecStdio(options?) mapping stdin: false -> ["ignore","inherit","inherit"], otherwise "inherit". execSandbox uses this helper; tests cover default, true, and false behaviors.
Command reference docs docs/reference/commands.mdx, docs/reference/commands-nemohermes.mdx	Document stdin forwarding as the default, add --no-stdin for scripted/CI one-shot runs, document --stdin to override wrappers, and update examples and flags tables in both main and advanced exec sections.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

integration: openclaw, area: cli, area: sandbox, feature

Suggested reviewers

• cv

Poem

A rabbit taps the stdin gate,
Default open — streams relate.
One-shot scripts can close the door,
Flags decide if bytes will pour.
Hopping docs and tests galore. 🐇

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	⚠️ Warning	The title is misleading: stdin is inherited by default, and closure is opt-in via --no-stdin rather than the default behavior.	Rename it to reflect opt-in stdin closure, e.g. "fix(cli): add opt-in stdin closure for sandbox exec".

✅ Passed checks (3 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

🧹 Nitpick comments (1)

docs/reference/commands-nemohermes.mdx (1)

528-535: ⚡ Quick win

Use active voice in stdin forwarding descriptions.

Lines 528 and 761 use passive voice ("Caller stdin is forwarded by default"). Rewrite to active voice for consistency with the documentation style guide:

• "NemoClaw forwards caller stdin by default for compatibility with terminal, pipe, and SSH workflows."

instead of "Caller stdin is forwarded by default for compatibility with terminal, pipe, and SSH workflows."

Also applies to: 761-763

🤖 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 `@docs/reference/commands-nemohermes.mdx` around lines 528 - 535, Replace the
passive-voice sentence "Caller stdin is forwarded by default for compatibility
with terminal, pipe, and SSH workflows." in
docs/reference/commands-nemohermes.mdx with an active-voice sentence;
specifically change it to "NemoClaw forwards caller stdin by default for
compatibility with terminal, pipe, and SSH workflows." Make this same
replacement at both occurrences (the one around lines 528–535 and the other
around lines 761–763) so the file consistently uses active voice.

Source: Coding guidelines

🤖 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 `@docs/reference/commands-nemohermes.mdx`:
- Around line 528-535: Replace the passive-voice sentence "Caller stdin is
forwarded by default for compatibility with terminal, pipe, and SSH workflows."
in docs/reference/commands-nemohermes.mdx with an active-voice sentence;
specifically change it to "NemoClaw forwards caller stdin by default for
compatibility with terminal, pipe, and SSH workflows." Make this same
replacement at both occurrences (the one around lines 528–535 and the other
around lines 761–763) so the file consistently uses active voice.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 81828124-6f04-468d-af48-7b377cca23a2

📥 Commits

Reviewing files that changed from the base of the PR and between 158f575 and bf7c756.

📒 Files selected for processing (6)

• docs/reference/commands-nemohermes.mdx
• docs/reference/commands.mdx
• src/commands/sandbox/exec.test.ts
• src/commands/sandbox/exec.ts
• src/lib/actions/sandbox/exec.test.ts
• src/lib/actions/sandbox/exec.ts

[HwangJohn]

@cv

Thanks again for the approval.

I fixed the signed-commit requirement and the current commits are now GitHub-verified. The remaining required checks appear to be waiting on maintainer workflow approval for the fork PR. Could you approve running the workflows when convenient?

[HwangJohn]

Pushed a signed follow-up commit to sync the generated docs/reference/commands-nemohermes.mdx output and address the Fern Preview docs:check-agent-variants failure.

Validation on DGX Spark/Linux:

• npm run docs:check-agent-variants passes
• npm run docs passes with 0 errors; Fern only reports the existing upgrade warning

The fork PR workflows appear to be awaiting maintainer approval again after this push.

[coderabbitai]

🧹 Nitpick comments (1)

docs/reference/commands-nemohermes.mdx (1)

442-442: ⚡ Quick win

Standardize --stdin/--no-stdin flag descriptions across both exec sections.

Both table entries mix a complete sentence with a label-value pattern and violate the guideline that colons should only introduce lists. As per coding guidelines, documentation sentences must end with periods. Combine into a single sentence with a parenthetical for consistency with the table style elsewhere in the file (see line 617: Timeout in seconds. Use '0' for no timeout).

• docs/reference/commands-nemohermes.mdx#L442-L442: Change Force caller stdin forwarding or closure. Default: forward stdin to Force caller stdin forwarding or closure (default: forward stdin).
• docs/reference/commands-nemohermes.mdx#L618-L618: Change Force caller stdin forwarding or closure. Default: forward stdin to Force caller stdin forwarding or closure (default: forward stdin).

🤖 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 `@docs/reference/commands-nemohermes.mdx` at line 442, Update the two table
entries to use a single consistent sentence with a parenthetical default: in
docs/reference/commands-nemohermes.mdx at 442-442 change the cell text from
"Force caller stdin forwarding or closure. Default: forward stdin" to "Force
caller stdin forwarding or closure (default: forward stdin)." and in the same
file at 618-618 change the cell text from "Force caller stdin forwarding or
closure. Default: forward stdin" to "Force caller stdin forwarding or closure
(default: forward stdin)."

Source: Coding guidelines

🤖 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 `@docs/reference/commands-nemohermes.mdx`:
- Line 442: Update the two table entries to use a single consistent sentence
with a parenthetical default: in docs/reference/commands-nemohermes.mdx at
442-442 change the cell text from "Force caller stdin forwarding or closure.
Default: forward stdin" to "Force caller stdin forwarding or closure (default:
forward stdin)." and in the same file at 618-618 change the cell text from
"Force caller stdin forwarding or closure. Default: forward stdin" to "Force
caller stdin forwarding or closure (default: forward stdin)."

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 7296f819-aa3b-4213-93bf-423c9f8fec64

📥 Commits

Reviewing files that changed from the base of the PR and between 0006d1a and 9dcbeaa.

📒 Files selected for processing (1)

• docs/reference/commands-nemohermes.mdx

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28813941726
Workflow ref: validation/pr-5388-8bccc991
Requested targets: (default — all supported)
Requested jobs: shields-config
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
shields-config	✅ success

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28817029378
Workflow ref: validation/pr-5388-40af01d5
Requested targets: (default — all supported)
Requested jobs: shields-config,sandbox-operations
Summary: 2 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
sandbox-operations	✅ success
shields-config	✅ success

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28829674160
Workflow ref: validation/pr-5388-d7368664
Requested targets: (default — all supported)
Requested jobs: sessions-agents-cli,sandbox-operations,shields-config
Summary: 3 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
sandbox-operations	✅ success
sessions-agents-cli	✅ success
shields-config	✅ success