fix(rebuild): keep compatible-endpoint reasoning through recovered recreate (#7940)

[yimoj]

Summary

A rebuild that has to recover the recorded provider from the registered gateway credential replaced the sandbox with no reasoning configuration: the replacement recorded compatibleEndpointReasoningEffort = null even though the authoritative resume configuration carried high, so the effort had to be restored by hand with inference set --reasoning-effort high. Three NemoClaw-owned gaps combined, and all three are fixed here. The documented contract in docs/inference/configure-model-capabilities.mdx — "a resumed onboard and nemoclaw <sandbox-name> rebuild both replay those recorded values" — now holds on the recovered path too. No new flag, environment variable, or configuration surface: the reporter's command is rebuild --yes, and it works unchanged.

Related Issue

Fixes #7940

Changes

• src/lib/onboard/session-updates.ts: OnboardSessionUpdateInput and toSessionUpdates() never carried compatibleEndpointReasoningEffort, so the value the callers in machine/handlers/provider-inference.ts supply was dropped before the session was written — and therefore before the registry entry that onboard/sandbox-registration.ts writes from that session. SessionUpdates already supported the field. The normalizer now maps it, keeping the undefined leave-unchanged versus explicit null clear semantics, and normalizing through normalizeReasoningEffort so an unrecognized value clears the recorded effort instead of persisting an effort the endpoint never received. This gap alone also made a fresh compatible-endpoint onboard with NEMOCLAW_REASONING_EFFORT=high record null.
• src/lib/actions/sandbox/rebuild-recreate-phase.ts: the recreate isolates the ambient onboard-selection environment so an unrelated onboard cannot steer it ([Ubuntu][Upgrade] installer auto-rebuild destroys existing sandboxes then fails to recreate when ambient env/session does not match the original config #5735), but it re-seeded only NEMOCLAW_POLICY_TIER. Both the recovered provider selection and src/lib/onboard/dockerfile-patch.ts — which bakes ARG NEMOCLAW_REASONING_EFFORT into the sandbox image — read the value from process.env, so the inner onboard --resume ran with no reasoning inputs. The recreate now re-seeds NEMOCLAW_REASONING and NEMOCLAW_REASONING_EFFORT from the authoritative resumeConfig inside the isolated window, only for the compatible-endpoint provider that can use them. The existing isolation restore returns the caller's ambient values on success and on failure, so the seed stays scoped to the recreate.
• src/lib/onboard/machine/handlers/provider-inference.ts: the recovered branch reaches resolveRecoveredProviderCredentialReuse() (no host credential copy, validated gateway credential) and sets reuseGatewayCredentialWithoutLocalKey, which short-circuits validateSelectedRemoteModel() — the only caller of configureCompatibleEndpointReasoning[Effort]() for a custom endpoint. The selection therefore reported no reasoning at all and cleared the recorded values. The handler now replays the recorded mode and effort for that same route when the selection reused the gateway credential. This is the boundary that owns the recorded route, so the fix also covers a plain recovered onboard --resume, not only a rebuild recreate.
• src/lib/actions/sandbox/rebuild-recreate-reasoning.test.ts (new): the recreate observes the recorded values, ambient values are restored on success and on a failed recreate, a resume configuration that no longer carries an effort clears it for the recreate, and a provider that cannot use reasoning still sees the isolated environment ([Ubuntu][Upgrade] installer auto-rebuild destroys existing sandboxes then fails to recreate when ambient env/session does not match the original config #5735 unchanged).
• src/lib/onboard/machine/handlers/provider-inference-authoritative-recovery.test.ts, src/lib/onboard/session-updates.test.ts, test/helpers/rebuild-flow-lifecycle-cases.ts: regression coverage for the recovered gateway-credential replay, the normalizer's nullable contract, and the rebuild lifecycle case that now asserts the effort survives.
• Follow-up commit 1b1bf3e39 (CodeRabbit finding): the replay applied the recorded values without naming them, so an exported NEMOCLAW_REASONING/NEMOCLAW_REASONING_EFFORT that disagreed with the recorded value was discarded silently — the exact no-op No supported path to set NEMOCLAW_REASONING on an existing sandbox; local reasoning models stall the agent idle timeout #7462 removed from the sibling resumed-selection path. The replay now emits the same describeIgnoredReasoningEnv() / describeIgnoredReasoningEffortEnv() report before configuring, extracted into replayRecoveredCompatibleEndpointReasoning() to keep handleProviderInferenceState under the Biome cognitive-complexity budget. A rebuild recreate seeds the environment from the same recorded configuration, so it stays silent. Covered by a new case that fails without the source change, strengthened in 2b0610047 to assert that the report names the recorded values, not only the ignored ambient ones.

Each new assertion was confirmed to fail without its corresponding source change.

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: no user-visible surface changes. docs/inference/configure-model-capabilities.mdx already documents the behavior this restores ("Onboarding records the reasoning flag and the reasoning effort in the sandbox's session and registry entry. A resumed onboard and nemoclaw <sandbox-name> rebuild both replay those recorded values"), and the inference set --reasoning-effort contract, the route rules, and the reasoning-effort inputs are all unchanged.
• 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: the credential path is untouched. The recovered branch still reuses the validated gateway credential and still skips validateSelectedRemoteModel(); this change only replays the already-recorded reasoning mode and effort for that selection, and no credential value is read, written, logged, or moved. The reseeded environment values are the two reasoning variables, taken from the authoritative resume configuration rather than the ambient environment, and they are restored by the existing #5735 isolation restore on success and failure — so ambient-environment isolation is preserved, not weakened. codex review --base origin/main reports no findings at head 1b1bf3e39.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-accurate-no-change
• Evidence: reviewed the changed sources against the reasoning-effort documentation. docs/inference/configure-model-capabilities.mdx already states that a resumed onboard and nemoclaw <sandbox-name> rebuild replay the recorded reasoning flag and reasoning effort, and that an exported NEMOCLAW_REASONING/NEMOCLAW_REASONING_EFFORT does not change them; that is exactly the contract this change restores on the recovered path, so the page is accurate before and after. docs/reference/commands.mdx documents inference set --reasoning-effort, which is unchanged. No new flag, environment variable, default, error message, or command output is introduced, so no page needs an edit and no changelog surface changes. Review performed by the primary agent in this session; no separate subagent surface was used. Re-reviewed at head 1b1bf3e39 after the CodeRabbit follow-up: that commit adds an operator-facing report that reuses the existing Ignoring NEMOCLAW_REASONING... message already documented on the same page, so no page needs an edit. Re-checked at head 2b0610047: that commit strengthens a test assertion only, so no documentation change is needed. The governing AGENTS.md blob remains c052d60aa.
• Agent: Claude Code

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 validate:pr passed after refreshing origin/main when hooks were skipped or unavailable — npm run validate:pr after git fetch origin main and a rebase onto origin/main 387cb0864: all prek pre-commit hooks, commitlint, and pre-push hooks Passed (exit 0). commitlint reports 0 problems and 1 footer-leading-blank warning for the Signed-off-by: trailer that follows the Fixes line.

• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npx vitest run --project cli src/lib/onboard/session-updates.test.ts src/lib/actions/sandbox/rebuild-recreate-reasoning.test.ts src/lib/onboard/machine/handlers/provider-inference-authoritative-recovery.test.ts src/lib/actions/sandbox/rebuild-env-isolation.test.ts src/lib/actions/sandbox/rebuild-flow.test.ts src/lib/onboard/setup-nim-flow.test.ts → 6 files / 136 tests passed; npm run typecheck:cli and npm run checks:repository clean

• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: npm test at head 1b1bf3e39 → 23188 passed, 14 failed across 8 files, every one pre-existing or load-induced and unrelated to this change:

  • test/install-station-dgx-os.test.ts (5), test/install-station-host-preparation.test.ts (3), test/install-station-package-transaction.test.ts (1): this host has a pending reboot (/var/run/reboot-required, dated 2026-07-28), so station-prepare refuses with A reboot is pending on the Station factory image / An unrelated reboot is already pending. All 9 reproduce identically in a clean origin/main worktree.
  • test/issue-5667-hosted-inference-model-namespace.test.ts (1): reproduces identically in a clean origin/main worktree, in isolation.
  • test/package-contract/managed-image-registry-transport.test.ts (1): the packed-CLI --omit=dev install fails registry resolution with npm error notarget No matching version found for @aws-sdk/core@^3.977.3, an upstream dependency-resolution failure with no relation to this change.
  • test/gateway-state-reconcile-2276.test.ts, test/rebuild-credential-preflight.test.ts, test/langchain-deepagents-code-image-credentials.test.ts (1 each): 15-60 s timeouts under full-suite parallel load. Re-running exactly those three files on this branch passes 143/143 in 80 s. The first two exercise the rebuild lifecycle this change touches, so they were re-run specifically to confirm the change is not the cause.

• 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)

Reporter-workflow E2E (Linux x86_64, real worktree CLI)

Every command below ran the worktree CLI (./bin/nemoclaw.js), never a global nemoclaw. Gateway port 8194 with an isolated state root (~/.nemoclaw/gateways/8194), sandbox e2e-7940-effort, a local OpenAI-compatible mock endpoint on http://127.0.0.1:8000/v1, a configured Telegram channel, and presets telegram,local-inference. The reporter's step 3 is reproduced by leaving COMPATIBLE_API_KEY out of the rebuild environment while the validated gateway credential stays registered, which is what forces the recovered-provider branch.

Before the fix (dist built from origin/main):

$ NEMOCLAW_REASONING=true NEMOCLAW_REASONING_EFFORT=high ./bin/nemoclaw.js onboard --fresh --non-interactive ...
  session.compatibleEndpointReasoningEffort = null          # the normalizer dropped it
  registry.compatibleEndpointReasoningEffort = null
  generated openclaw.json "reasoning_effort" = "high"       # baked from the ambient env

$ ./bin/nemoclaw.js e2e-7940-effort inference set --provider compatible-endpoint --model ... --reasoning-effort high
  session.compatibleEndpointReasoning = true, effort = high  # documented pre-rebuild state restored
  registry effort = high

$ ./bin/nemoclaw.js e2e-7940-effort rebuild --yes            # no COMPATIBLE_API_KEY in the environment
  Revalidating recovered compatible-endpoint identity…
  Reusing existing gateway credential…
  exit 0
  session.compatibleEndpointReasoning = null                 # the recorded reasoning mode was lost

The recorded effort survived that run only because the same normalizer defect also dropped the recovered null; the reasoning mode, which the normalizer did carry, was cleared to null — the reporter's defect.

After the fix (dist built from this branch, same commands):

$ NEMOCLAW_REASONING=true NEMOCLAW_REASONING_EFFORT=high ./bin/nemoclaw.js onboard --fresh --non-interactive ...
  session reasoning = true, effort = high
  registry reasoning = true, effort = high

$ ./bin/nemoclaw.js e2e-7940-effort rebuild --yes            # no COMPATIBLE_API_KEY, same recovered branch
  exit 0
  session reasoning = true, effort = high
  registry reasoning = true, effort = high
  in-sandbox /sandbox/.openclaw/openclaw.json "reasoning_effort" = "high"
  image built by the recreate (nemoclaw-sandbox-local:e2e-7940-effort-1785467801916) has the same value baked in

All three recording surfaces the issue names — onboard session, replacement registry row, and generated OpenClaw configuration — keep high across the recovered rebuild.

---

Signed-off-by: Yimo Jiang yimoj@nvidia.com

Summary by CodeRabbit

• New Features

  • Preserved compatible-endpoint reasoning mode and effort settings during onboarding recovery and sandbox recreation.
  • Added support for storing, restoring, and clearing reasoning effort settings in onboarding sessions.
  • Ensured recovered settings override conflicting ambient configuration when applicable.

• Bug Fixes

  • Prevented reasoning configuration from being lost during sandbox rebuilds or credential-based recovery.

• Tests

  • Added coverage for successful recovery, failure cleanup, stale-value removal, and provider-specific behavior.

[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: c8ba998c-fab2-4e94-ba21-5958b6db457b

📥 Commits

Reviewing files that changed from the base of the PR and between 1b1bf3e and ac9fba2.

📒 Files selected for processing (1)

• src/lib/onboard/machine/handlers/provider-inference-authoritative-recovery.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/onboard/machine/handlers/provider-inference-authoritative-recovery.test.ts

---

📝 Walkthrough

Walkthrough

The change preserves compatible-endpoint reasoning effort across session updates, provider recovery, and sandbox recreation. It seeds isolated rebuild environments with recovered reasoning values and adds coverage for normalization, restoration, cleanup, and unsupported providers.

Changes

Compatible-endpoint reasoning recovery

Layer / File(s)	Summary
Session and provider recovery src/lib/onboard/session-updates.ts, src/lib/onboard/session-updates.test.ts, src/lib/onboard/machine/handlers/provider-inference.ts, src/lib/onboard/machine/handlers/provider-inference-authoritative-recovery.test.ts	Session updates normalize compatibleEndpointReasoningEffort. Recovered gateway credentials restore stored reasoning settings and propagate them through provider selection.
Rebuild environment handoff src/lib/actions/sandbox/rebuild-recreate-phase.ts, src/lib/actions/sandbox/rebuild-recreate-reasoning.test.ts, test/helpers/rebuild-flow-lifecycle-cases.ts	Sandbox recreation seeds reasoning environment variables from recovered configuration. Tests verify build-time propagation, cleanup, restoration, and ambient-value isolation.

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

Sequence Diagram(s)

sequenceDiagram
  participant ProviderInference
  participant RebuildPhase
  participant SandboxImageBuild
  ProviderInference->>RebuildPhase: Restore compatible-endpoint reasoning settings
  RebuildPhase->>RebuildPhase: Set reasoning environment variables
  RebuildPhase->>SandboxImageBuild: Pass seeded reasoning configuration
  RebuildPhase->>RebuildPhase: Restore ambient environment values

Loading

Possibly related issues

• NVIDIA/NemoClaw issue 7940 — Covers preserving compatible-endpoint reasoning effort through rebuild recreation, provider recovery, and session updates.

Possibly related PRs

• NVIDIA/NemoClaw#7366 — Both changes scope and restore environment variables during sandbox recreation.
• NVIDIA/NemoClaw#7788 — Both changes modify sandbox recreation state handling and rebuild flows.
• NVIDIA/NemoClaw#7840 — Both changes modify shared rebuild flows and lifecycle tests.

Suggested labels: area: sandbox, area: onboarding, bug-fix

Suggested reviewers: cv, apurvvkumaria

🚥 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 identifies the rebuild fix and preservation of compatible-endpoint reasoning during recovered recreation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ 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/7940-preserve-rebuild-reasoning-effort

---

_{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 in commit ac9fba2 in the fix/7940-preserve-re... branch remains at 96%, unchanged from commit 7eb0369 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit ac9fba2 in the fix/7940-preserve-re... branch remains at 81%, unchanged from commit 7eb0369 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 7eb0369	fix/7940-preserve-re... ac9fba2	+/-
src/lib/shields/index.ts	69%	69%	0%
src/lib/onboard...er-inference.ts	95%	95%	0%
src/lib/actions...create-phase.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/actions...ld-mcp-phase.ts	91%	93%	+2%
src/lib/actions...-gpu-opt-out.ts	89%	92%	+3%
src/lib/onboard...asoning-mode.ts	89%	93%	+4%
src/lib/onboard...sion-updates.ts	65%	70%	+5%
src/lib/state/u...-files-probe.ts	63%	70%	+7%
src/lib/actions...uild-shields.ts	50%	67%	+17%

---

_{Updated July 31, 2026 14:03 UTC}

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

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: cloud-onboard, inference-routing, network-policy, onboard-repair, onboard-resume, rebuild-openclaw, state-backup-restore

Workflow run details

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

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@src/lib/onboard/machine/handlers/provider-inference.ts`:
- Around line 646-665: In the credential-reuse recovery branch of the provider
inference handler, call describeIgnoredReasoningEnv and
describeIgnoredReasoningEffortEnv with the effective recorded reasoning and
effort values before invoking configureCompatibleEndpointReasoning and
configureCompatibleEndpointReasoningEffort. Preserve the existing fallback
selection and configuration behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: a80dc757-4242-4fbf-b266-908900c29cbd

📥 Commits

Reviewing files that changed from the base of the PR and between 387cb08 and 5651c6f.

📒 Files selected for processing (7)

• src/lib/actions/sandbox/rebuild-recreate-phase.ts
• src/lib/actions/sandbox/rebuild-recreate-reasoning.test.ts
• src/lib/onboard/machine/handlers/provider-inference-authoritative-recovery.test.ts
• src/lib/onboard/machine/handlers/provider-inference.ts
• src/lib/onboard/session-updates.test.ts
• src/lib/onboard/session-updates.ts
• test/helpers/rebuild-flow-lifecycle-cases.ts

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In
`@src/lib/onboard/machine/handlers/provider-inference-authoritative-recovery.test.ts`:
- Around line 196-198: Update the warning assertions in the provider-inference
recovery test to verify that each message includes both the ignored ambient
value and the recorded replacement value: `true` for reasoning mode and `high`
for reasoning effort. Keep the existing checks for the NEMOCLAW_REASONING and
NEMOCLAW_REASONING_EFFORT warnings while asserting their complete recorded-value
behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 88f43e00-6139-476f-9e5e-6b8c6b32b3a9

📥 Commits

Reviewing files that changed from the base of the PR and between 5651c6f and 1b1bf3e.

📒 Files selected for processing (2)

• src/lib/onboard/machine/handlers/provider-inference-authoritative-recovery.test.ts
• src/lib/onboard/machine/handlers/provider-inference.ts

[jyaunches]

Approved after exact-revision merge gate: current head/base CI and selected E2E evidence pass, the linked supported regression is covered by tests, contributor requirements pass, and no unresolved correctness or security findings remain.