fix(onboard): preserve portable model intent

[senthilr-nv]

Summary

Fresh Portable onboarding removed an explicit NEMOCLAW_MODEL before provider selection and replaced it with qwen3-vl:4b.
This change preserves a nonempty explicit model until the existing provider validator evaluates it, while retaining descriptor and resume authority.

Related Issue

Part of #9200.
Related to #9208.

Changes

• Preserve a nonempty NEMOCLAW_MODEL during fresh Portable onboarding.
• Keep qwen3-vl:4b as the default when the value is absent or empty.
• Keep a valid Portable inference descriptor authoritative over ambient model input.
• Clear NEMOCLAW_MODEL and NEMOCLAW_PROVIDER_MODEL during resume so recorded provider and model state remains authoritative.
• Add regression coverage for explicit, empty, absent, malformed, descriptor, restore, and resume behavior.
• Update the compatible-endpoint documentation for the fresh and resume model-selection contract.

The escaped defect was not detected because the existing environment-scope tests covered hostile selector removal but did not assert that legitimate fresh model intent reached provider validation.
The new tests exercise that production boundary and the sibling fallback selector.

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: Independent nine-category security review passed on commit 490d05919 with no findings.
• 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-updated
• Evidence: docs/inference/set-up-openai-compatible-endpoint.mdx; the review covered the fresh explicit/default/descriptor contract, resume authority, generated OpenClaw, Hermes, and Deep Agents variants, and the writing rules.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

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
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project cli src/lib/onboard/portable-environment-scope.test.ts src/lib/onboard/providers.test.ts passed 64 tests. ./node_modules/.bin/vitest run --changed upstream/main --project cli --project plugin --project e2e-support passed 1,520 tests across 120 files.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: npm run test:fast was not used as candidate evidence because exact-main tests hit the private /tmp authority guard and the macOS host lacks GNU timeout; neither test is selected by the changed dependency graph.
• 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) — npm run docs passed with 0 errors and 2 pre-existing suppressed warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• New Features

  • Portable onboarding supports explicit model selection through NEMOCLAW_MODEL.
  • When no model is provided, onboarding defaults to qwen3-vl:4b.
  • Portable resume reuses the provider and model recorded during onboarding.

• Bug Fixes

  • Improved validation of malformed model configuration.
  • Activation profile settings now take precedence during setup.

• Documentation

  • Updated setup guidance for model selection and fallback behavior.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[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: 702b2be3-42c3-4cf8-8c1c-e48502e62604

📥 Commits

Reviewing files that changed from the base of the PR and between 0a8991a and 490d059.

📒 Files selected for processing (1)

• src/lib/onboard/portable-environment-scope.test.ts

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

• src/lib/onboard/portable-environment-scope.test.ts

Included review availability: Your plan includes up to 12 reviews per rolling hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

Portable onboarding now preserves configured models, prefers activation-profile input, and falls back to qwen3-vl:4b. It manages NEMOCLAW_PROVIDER_MODEL, validates malformed values, clears ambient selectors, and documents fresh setup versus resume behavior.

Changes

Portable model selection

Layer / File(s)	Summary
Portable model resolution src/lib/onboard/session-bootstrap.ts	Portable onboarding manages NEMOCLAW_PROVIDER_MODEL and resolves the model from activation input, a trimmed existing NEMOCLAW_MODEL, or qwen3-vl:4b.
Model selection validation src/lib/onboard/portable-environment-scope.test.ts, docs/inference/set-up-openai-compatible-endpoint.mdx	Tests cover model precedence, malformed model rejection, and ambient selector cleanup. Documentation distinguishes fresh setup from resume behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: 🟡 Moderate · up to 490d0

The change preserves explicit model selection during onboarding and documents the updated behavior, with targeted tests passing. Merge should wait for the pending sensitive-path security review and completion or approval of the required quality gates.

Suggested labels: area: onboarding, bug-fix

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: preserving explicit Portable model intent during onboarding and resume.
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 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-portable-model-intent

---

_{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 490d059 in the codex/fix-portable-m... branch remains at 96%, unchanged from commit 3707b8e in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 490d059 in the codex/fix-portable-m... branch remains at 82%, unchanged from commit 071e090 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 071e090	codex/fix-portable-m... 490d059	+/-
src/lib/onboard...ce-lifecycle.ts	93%	89%	-4%
src/lib/policy/index.ts	67%	67%	0%
src/lib/onboard...on-bootstrap.ts	76%	76%	0%
src/lib/agent/defs.ts	97%	97%	0%
src/lib/agent/s...store-reader.ts	89%	89%	0%
src/lib/onboard...ider-profile.ts	100%	100%	0%
src/lib/actions...aged-profile.ts	84%	88%	+4%
src/lib/onboard...carryforward.ts	88%	96%	+8%
src/lib/actions...er-lifecycle.ts	85%	94%	+9%
src/lib/actions...ld-mcp-phase.ts	87%	98%	+11%

---

_{Updated August 17, 2026 03:36 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-9270.docs.buildwithfern.com/nemoclaw

[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): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — Portable inference descriptor at docs/inference/set-up-openai-compatible-endpoint.mdx:139: Keep `Portable inference descriptor`; repository documentation and source already use this term.
• justified — ambient model selectors at docs/inference/set-up-openai-compatible-endpoint.mdx:139: Keep `ambient model selectors`; the modifier identifies the selector source that portable resume ignores.
• replace — recorded provider and model authority at docs/inference/set-up-openai-compatible-endpoint.mdx:139: Replace `recorded provider and model authority` with `recorded route` when the sentence refers to the persisted provider and model selection.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite for the commit under review.

Recommended E2E: None

Manual-only E2E: onboard-repair, onboard-resume, cloud-onboard
The manual PR workflow does not run these selectors for the commit under review. Run them from reviewed code on main.

Workflow run details

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