fix(inference): pre-flight sandbox read before mutating the inference route

[rluo8]

Summary

nemoclaw inference set --no-verify --sandbox <name> against a sandbox whose container is stopped crashed with an uncaught SandboxConfigError (raw Node stack, exit 1) and left a half-applied switch: the gateway route and registry were already mutated to the new model while the in-sandbox openclaw.json still pointed at the old one. The in-sandbox config is now read as a pre-flight gate before any mutation, so an unreadable config aborts cleanly and atomically (nothing mutated) with a clear message instead of a stack trace.

Related Issue

Closes #6997

Changes

• src/lib/actions/inference-set.ts: add readInSandboxConfigOrFail(), which reads the in-sandbox config and converts a SandboxConfigError (the config could not be read or parsed — most commonly a stopped sandbox) into a clean InferenceSetError, preserving the original diagnostic lines and exit code. It appends a Start the sandbox and retry. hint only for the stopped-sandbox case (the one that reports Is the sandbox running?) — not for a corrupt/unparseable config, which starting the sandbox would not fix. Call it before the gateway-route mutation (captureOpenshell inference set) and the registry writes, replacing the former crash-prone read that ran after those mutations. Protected by the tests below.
• src/lib/actions/inference-set-degraded-state.test.ts: rewrite the read-failure case to exercise the real SandboxConfigError path and assert zero mutation (route-set, updateSandbox, writeSandboxConfig, restartSandboxGateway all uncalled) — locking the ordering so moving the read back after the mutations fails the test. The prior assertion asserted the buggy half-applied state.
• test/inference-set-preflight.test.ts: unit tests for the helper — readable path, stopped-sandbox conversion (error type, message, exit code), parse-failure conversion (no start hint), and pass-through of unrelated errors.

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: behavior/error-message change on an existing command; no documented behavior contract changes.
• 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

• 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 check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification:
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Rui Luo ruluo@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Inference configuration changes now validate sandbox configuration before applying updates.
  • Failed or unreadable sandbox configuration stops the operation cleanly, preventing partial route or registry changes.
  • Error messages now provide guidance to start the sandbox and retry when applicable.

• Tests

  • Added coverage for successful reads, stopped sandboxes, parsing failures, and unrelated errors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9ad9a482-f8f2-4b3b-becb-f60d27437311

📥 Commits

Reviewing files that changed from the base of the PR and between c1bda80 and 6ef59c9.

📒 Files selected for processing (3)

• src/lib/actions/inference-set-degraded-state.test.ts
• src/lib/actions/inference-set.ts
• test/inference-set-preflight.test.ts

---

📝 Walkthrough

Walkthrough

The inference-set command now reads and validates the in-sandbox configuration before changing gateway or registry state. Sandbox read failures become actionable InferenceSetError instances, and tests verify that failed pre-flight checks perform no mutations.

Changes

Inference-set pre-flight validation

Layer / File(s)	Summary
Sandbox configuration error translation src/lib/actions/inference-set.ts, test/inference-set-preflight.test.ts	Adds readInSandboxConfigOrFail, which preserves diagnostics and exit codes, adds a stopped-sandbox hint, and leaves unrelated errors unchanged.
Pre-flight mutation gate src/lib/actions/inference-set.ts, src/lib/actions/inference-set-degraded-state.test.ts	Moves the sandbox configuration read before gateway and registry mutations and verifies failed reads do not invoke route updates or updateSandbox.

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

Sequence Diagram(s)

sequenceDiagram
  participant runInferenceSet
  participant readInSandboxConfigOrFail
  participant readSandboxConfig
  participant OpenShellGateway
  participant NemoClawRegistry

  runInferenceSet->>readInSandboxConfigOrFail: Read sandbox configuration
  readInSandboxConfigOrFail->>readSandboxConfig: Load configuration
  readSandboxConfig-->>readInSandboxConfigOrFail: Configuration or SandboxConfigError
  readInSandboxConfigOrFail-->>runInferenceSet: Configuration or InferenceSetError
  runInferenceSet->>OpenShellGateway: Update inference route
  runInferenceSet->>NemoClawRegistry: Update registry

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7004: Implements the same pre-flight gate and degraded-state assertions.

Suggested labels: bug-fix, area: sandbox

Suggested reviewers: ericksoa, cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: reading the sandbox config before mutating the inference route.
Linked Issues check	✅ Passed	The code now fails cleanly on stopped-sandbox config reads and aborts before route or registry mutations, matching #6997.
Out of Scope Changes check	✅ Passed	All changes are directly related to the pre-flight sandbox-read fix and its tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/6997-inference-set-preflight-sandbox

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the fix/6997-inference-s... branch remains at 80%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 8c52687	fix/6997-inference-s... 4303d48	+/-
src/lib/inferen...lama/process.ts	100%	50%	-50%
src/lib/onboard...box-prebuild.ts	88%	69%	-19%
src/lib/inferen...er-lifecycle.ts	71%	65%	-6%
src/lib/platform.ts	89%	84%	-5%
src/lib/messagi...flow-planner.ts	93%	93%	0%
src/lib/onboard...tch-recreate.ts	94%	95%	+1%
src/lib/actions...eway-restart.ts	90%	93%	+3%
src/lib/onboard...u-patch-mode.ts	90%	93%	+3%
src/lib/onboard...host-anchors.ts	90%	94%	+4%
src/lib/domain/.../connect-env.ts	89%	97%	+8%

---

_{Updated July 16, 2026 08:47 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: inference-routing, network-policy

1 optional E2E recommendation

• openclaw-inference-switch

Workflow run details

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

[cv]

Approved on exact head 4303d48. The accepted #6997 path now reads the in-sandbox config before the first route/registry mutation, converts only SandboxConfigError while preserving diagnostics and exit code, and leaves unrelated failures untouched. Security review found no auth, credential, injection, SSRF, policy, dependency, or secret-exposure regression. Local evidence: 127 CLI inference tests + 4 integration preflight tests, CLI typecheck, and check:diff passed. Exact-diff E2E plan 016cb6b768111a8a6a2dd7bb5d775a07c63e8f3892d20b53042fb97d380add27 passed inference-routing and network-policy; advisor attempt 4 and CodeRabbit are clean.