fix(onboard): report an ignored NEMOCLAW_REASONING instead of silently keeping the recorded flag

[souvikDevloper]

Summary

A resumed onboard replays the sandbox's recorded selection, so the recorded compatible-endpoint reasoning flag wins over an ambient NEMOCLAW_REASONING by design (#5735). That precedence was silent. Now a resumed onboard that sees an explicit NEMOCLAW_REASONING disagreeing with the recorded value prints the recorded value and the command that re-reads the variable, instead of ignoring the variable without output.

Related Issue

Refs #7462.

This addresses the reporter's first question — "whether the intended path to set this on an existing sandbox is a different command/flag" — and the silent no-op behind it. It does not change the idle-timeout behavior described in the second half of that issue; see Scope below.

Changes

• src/lib/onboard/reasoning-mode.ts: add describeIgnoredReasoningEnv(storedValue, cliName, env). Pure — it returns the message or null and touches no environment. It returns null unless the recorded value and NEMOCLAW_REASONING both normalize to a flag and disagree, so an unset, invalid, or matching variable stays quiet. cliName is a required parameter rather than a defaulted one so the Deep Agents CLI names its own binary in the message.
• src/lib/onboard/machine/handlers/provider-inference.ts: on the resume path, emit that message before calling configureCompatibleEndpointReasoning. Order matters — configureCompatibleEndpointReasoning overwrites process.env.NEMOCLAW_REASONING with the recorded value, so reading it afterwards can never see what the user asked for. The ternary became an if/else to hold the two statements.
• docs/inference/configure-model-capabilities.mdx: state in Apply Capability Changes that onboarding records the flag, that a resumed onboard and rebuild replay the recorded value, and what a resumed onboard reports on a mismatch.

No behavior other than output changes: the recorded value still wins, and nemoclaw onboard --fresh --name <sandbox> --recreate-sandbox is still the path that re-reads the variable.

Scope

The issue also asks whether reasoning-token stream progress should reset the LLM idle timeout (120s) detector. That timer is OpenClaw's — no NemoClaw source, script, or doc emits or configures that message — so it is not addressed here and needs a separate decision.

The rebuild path already reports its own isolation of ambient selection env (assessRebuildAmbientEnv in src/lib/actions/sandbox/rebuild-resume-preflight.ts), so it is left unchanged.

Type of Change

• Code change with doc updates

Quality Gates

• Tests added or updated for changed behavior
• Docs updated for user-facing behavior 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: maintainer review confirmed this is output-only; recorded precedence, credentials, routing, and written artifacts are unchanged, with mismatch/match regression coverage.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/inference/configure-model-capabilities.mdx; the exact-head review confirmed that resumed onboarding reports the mismatch while rebuild retains its existing generic ambient-environment notice. Focused tests, CLI/plugin builds, CLI type-checking, and npm run docs passed.
• Agent: Codex Desktop

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 — reasoning-mode.test.ts and provider-inference-reasoning-resume.test.ts: 9 passed.
• No secrets, API keys, or credentials committed

New tests:

• src/lib/onboard/reasoning-mode.test.ts — four cases over describeIgnoredReasoningEnv: the mismatch message names the recorded value and the recreate command; the CLI name comes from the caller; both sides normalize before comparing (no vs " YES " reports, yes vs 1 stays quiet); an unset, invalid, or unrecorded flag returns null.
• src/lib/onboard/machine/handlers/provider-inference.test.ts — a resumed compatible-endpoint sandbox recorded as reasoning=false under NEMOCLAW_REASONING=true logs both the ignored value and the recreate command and still resolves to false; the same sandbox recorded as true logs nothing.

Environment caveats — this checkout is Windows, and the following failures reproduce on a clean upstream/main with my commit stashed, so they are pre-existing and environment-specific, not caused by this change:

• provider-inference.test.ts > clears stale resumed state before writing a non-compatible artifact — O_NOFOLLOW is unavailable on this platform. This is the single failure in the targeted run above.
• npm run check:diff — the platform-matrix-sync hook and hadolint exit 127 (python3: command not found, hadolint not installed). Every other hook passed, including Biome format, Biome lint, SPDX headers, and shfmt.
• npm run docs — fails in scripts/generate-starter-prompt.mts with docs/resources/starter-prompt.md: use LF line endings, a CRLF artifact of the Windows checkout in a file this PR does not touch.

I have not run npm test or npm run check in full; this change is not repo-wide and does not touch the test harness. CI is the authority on all of the above.

---

Signed-off-by: Souvik Ghosh 138186578+souvikDevloper@users.noreply.github.com

Summary by CodeRabbit

• Bug Fixes
  • Resumed onboarding now reliably reuses the previously recorded reasoning setting for compatible-endpoint behavior.
  • When NEMOCLAW_REASONING in the environment conflicts with the recorded value, the recorded setting is used instead.
  • Improved, actionable logging explains the mismatch and provides a nemoclaw ... --recreate-sandbox command for remediation.
• Documentation
  • Updated “Apply Capability Changes” guidance to clarify persistence/replay of the reasoning flag during onboarding and sandbox rebuild flows, and how conflicts are handled.

[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]

📝 Walkthrough

Walkthrough

The onboarding flow detects conflicting NEMOCLAW_REASONING values, reports the recorded value and recreation command, preserves recorded reasoning during compatible-endpoint inference, and documents replay behavior across resumed onboarding and rebuild operations.

Changes

Reasoning replay handling

Layer / File(s)	Summary
Reasoning mismatch description src/lib/onboard/reasoning-mode.ts, src/lib/onboard/reasoning-mode.test.ts	Adds normalized comparison of recorded and ambient reasoning values, returning remediation text only when they differ, with unit coverage for mismatch and no-op cases.
Provider inference replay behavior src/lib/onboard/machine/handlers/provider-inference.ts, src/lib/onboard/machine/handlers/provider-inference-reasoning-resume.test.ts, docs/inference/configure-model-capabilities.mdx	Compatible-endpoint inference logs conflicting environment configuration before applying the recorded reasoning value; resume tests and documentation cover the replay behavior.

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

Sequence Diagram(s)

sequenceDiagram
  participant Onboarding
  participant ReasoningHelper
  participant CompatibleEndpoint
  Onboarding->>ReasoningHelper: Compare recorded and ambient NEMOCLAW_REASONING
  ReasoningHelper-->>Onboarding: Return mismatch message or null
  Onboarding->>CompatibleEndpoint: Apply recorded reasoning value
  CompatibleEndpoint-->>Onboarding: Return configured inference state

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: reporting ignored NEMOCLAW_REASONING during onboarding instead of silently preserving the recorded value.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / medium 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 · medium 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

1 optional E2E recommendation

• messaging-compatible-endpoint

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

🧹 Nitpick comments (1)

src/lib/onboard/reasoning-mode.ts (1)

27-30: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep this helper independent of process.env.

Line 30 makes a domain helper read global state through a default parameter. Require env and have provider-inference.ts pass process.env; the unit tests already provide a controlled environment.

Proposed refactor

 export function describeIgnoredReasoningEnv(
   storedValue: string | null | undefined,
   cliName: string,
-  env: NodeJS.ProcessEnv = process.env,
+  env: NodeJS.ProcessEnv,
 ): string | null {

 const ignoredReasoning = describeIgnoredReasoningEnv(
   compatibleEndpointReasoning,
   deps.cliName(),
+  process.env,
 );

As per path instructions, “keep domain/policy helpers pure (no process/env reads inside pure logic; use injected inputs for testability).”

🤖 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 `@src/lib/onboard/reasoning-mode.ts` around lines 27 - 30, Make the env
parameter of describeIgnoredReasoningEnv required, removing its process.env
default so the helper remains independent of global state. Update
provider-inference.ts to explicitly pass process.env at each call site, while
preserving the existing controlled env arguments in unit tests.

Source: Path instructions

🤖 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 `@docs/inference/configure-model-capabilities.mdx`:
- Around line 51-53: Update the documentation paragraph covering recorded
reasoning values and mismatch handling so it states that both resumed onboarding
and `nemoclaw <sandbox-name> rebuild` report an explicit NEMOCLAW_REASONING
conflict using the recorded value and recreate command, rather than limiting
this behavior to resumed onboarding.

---

Nitpick comments:
In `@src/lib/onboard/reasoning-mode.ts`:
- Around line 27-30: Make the env parameter of describeIgnoredReasoningEnv
required, removing its process.env default so the helper remains independent of
global state. Update provider-inference.ts to explicitly pass process.env at
each call site, while preserving the existing controlled env arguments in unit
tests.

🪄 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: fd238032-c070-484a-b671-a5937cf9e043

📥 Commits

Reviewing files that changed from the base of the PR and between 04e6dfa and 074bdbc.

📒 Files selected for processing (5)

• docs/inference/configure-model-capabilities.mdx
• src/lib/onboard/machine/handlers/provider-inference.test.ts
• src/lib/onboard/machine/handlers/provider-inference.ts
• src/lib/onboard/reasoning-mode.test.ts
• src/lib/onboard/reasoning-mode.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-reasoning-resume.test.ts`:
- Around line 37-43: Update the diagnostic-log assertion for the
NEMOCLAW_REASONING case in the test to verify that the emitted message includes
the recorded value “false,” not only the command guidance. Keep the existing
compatibleEndpointReasoning precedence assertion unchanged.

🪄 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: 4caaf10c-9ad6-4bc8-9b48-4150b93045bf

📥 Commits

Reviewing files that changed from the base of the PR and between 074bdbc and fe0863d.

📒 Files selected for processing (1)

• src/lib/onboard/machine/handlers/provider-inference-reasoning-resume.test.ts

[souvikDevloper]

Pushed 594f500e3. Status on the exact head, plus one CI item that needs a maintainer.

codebase-growth-guardrails — fixed

The failure on 074bdbcd7 was real:

FAIL: test size budget policy would be weakened or exceeded.
- src/lib/onboard/machine/handlers/provider-inference.test.ts: 1553 line(s) > 1500

That file is at 1493 lines on main, seven under defaultMaxLines, so the two new cases pushed it over. A legacyMaxLines entry is not an option — evaluateTestSizeBudgetViolations rejects a new legacy budget above defaultMaxLines and enforces monotonicity — so the tests moved to src/lib/onboard/machine/handlers/provider-inference-reasoning-resume.test.ts, following the split already used for route containment, recovery gating, and Station Express. provider-inference.test.ts is back to its base content and is no longer in the diff.

Now passing. scripts/check-test-file-size-budget.mts, npm run test:projects:check, and scripts/checks/test-title-style.mts also pass locally.

CodeRabbit findings

Applied — "Assert that the diagnostic displays the recorded value." Correct: the handler test verified precedence through the returned flag but would have passed if the message omitted false. It now asserts recorded as reasoning=false.

Not applied — "Document mismatch reporting for rebuild too." Rebuild reaches the branch but can never emit the notice, so the suggested wording would document behavior that does not exist.

rebuild-recreate-phase.ts:182 calls isolateAmbientRecreateEnv() immediately before the inner onboard({ resume: true, ... }) and restores only in the finally after it returns. NEMOCLAW_REASONING is in AMBIENT_RECREATE_ENV_VARS (rebuild-env-isolation.ts:49), so it is deleted from process.env for the whole recreate, including this branch. describeIgnoredReasoningEnv then reads an unset variable and returns null. The custom- and managed-image preflights (rebuild-custom-image-preflight.ts:87, rebuild-managed-image-preflight.ts:122) separately set it to the recorded value, which is also null from this helper because the two sides agree.

Rebuild already reports its own isolation through assessRebuildAmbientEnv, so the ambient value is not silently dropped there either. The doc line is scoped to resumed onboarding deliberately. Happy to widen it if a maintainer reads that boundary differently.

Needs a maintainer: workflow runs are action_required

Every PR CI workflow on fe0863dac is parked at action_required rather than having run:

Workflow	Status
CI / Pull Request	action_required
CI / Commit Lint	action_required
CI / DCO Check	action_required
CI / Documentation Writer Review	action_required
Docs / CLI Parity, Docs / Fern Preview	action_required
Security / Code Scanning, Security / Installer Hash Check	action_required
E2E / macOS	action_required

The runs that did execute are green: Codebase Growth Guardrails, Require Maintainer Edits, Assign Linked Issue Author, both PR review advisors, and CodeRabbit.

E2E / PR Gate Coordination is consequently sitting at pending waiting for PR CI, which is the shape that ends in "Timed out waiting for the trusted E2E verdict" if nothing approves the runs first. That timeout would be a symptom, not a defect in this change.

This needs someone with write access to approve the workflow runs on this head; I cannot clear it from the fork side. @cv could you kick these off, or point me at what is holding them.

Signed-off-by: Souvik Ghosh 138186578+souvikDevloper@users.noreply.github.com

[convexchaos]

Tested the documented procedure from docs/inference/configure-model-capabilities.mdx
verbatim on NemoClaw v0.0.92 / OpenShell 0.0.85 / OpenClaw 2026.7.1 (DGX Spark,
local vLLM, Nemotron-3-Super with --reasoning-parser nemotron_v3):

export NEMOCLAW_REASONING=true
nemoclaw onboard --fresh --name spark-nemo --recreate-sandbox

The recreate performed a full sandbox image build and passed all three GPU proofs,
so this was not the resume path. Afterwards:

openclaw.json → "reasoning": false
container env → NEMOCLAW_REASONING=false

Also tried: installer with NEMOCLAW_REASONING=true, rebuild --yes, and the
installer with NEMOCLAW_RECREATE_SANDBOX=1 — all left the value at false.
nemoclaw inference set exposes no capability flag.

So on this platform there appears to be no working path to set reasoning:true
on an existing sandbox, including the documented one. Happy to supply full
onboard output or a debug tarball.

[prekshivyas]

Reviewed at 84ad567. The change is output-only: recorded reasoning precedence, credentials, routing, and persisted state remain unchanged. Focused tests and docs validation pass; no unresolved review findings. Required E2E remains independently enforced.