refactor(snapshot): lower cognitive complexity ratchet to 184

[cv]

Summary

Continue the stacked cognitive-complexity ratchet by lowering the threshold from 186 to 184. This handles the tied 186 hotspots by extracting snapshot creation and moving the setupNim provider-choice guard out of the top-level onboard file.

Changes

• Lowered complexity/noExcessiveCognitiveComplexity from 186 to 184 in biome.json.
• Extracted snapshot creation handling from runSandboxSnapshot into runSnapshotCreate.
• Moved the setupNim no-provider-selected guard into src/lib/onboard/setup-nim-selection.ts so src/lib/onboard.ts stays net-neutral for the growth guardrail.
• Preserved snapshot create output and failure behavior.

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)

Verification

• npx @biomejs/biome lint --only=complexity/noExcessiveCognitiveComplexity --max-diagnostics=none .

• npm run typecheck:cli

• npx vitest run --project cli test/snapshot.test.ts test/openclaw-config-snapshot.test.ts test/security-sandbox-tar-traversal.test.ts src/lib/onboard/providers.test.ts src/lib/onboard/vllm-menu.test.ts

• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes

• Targeted tests pass for changed behavior

• Tests added or updated for new or changed behavior

• Full npm test passes (broad runtime changes only)

• No secrets, API keys, or credentials committed

• Docs updated for user-facing behavior changes

• 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: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

Release Notes

• Refactor
  • Extracted sandbox snapshot creation and messaging hydration into reusable helpers for clearer, consistent flows.
  • Improved snapshot-creation safeguards and logging while keeping existing behavior intact.
• New Features
  • Added explicit provider-choice enforcement during onboarding to fail fast on invalid selection.
• Tests
  • Expanded snapshot creation test coverage, including “sandbox not live” refusal and detailed failure/success output assertions.
• Chores
  • Adjusted Biome linter cognitive complexity threshold slightly.

[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: e2198e69-7f5e-4337-9806-d1d18bcce000

📥 Commits

Reviewing files that changed from the base of the PR and between af3257b and 0e2b7e7.

📒 Files selected for processing (1)

• src/lib/actions/sandbox/snapshot.test.ts

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

• src/lib/actions/sandbox/snapshot.test.ts

---

📝 Walkthrough

Walkthrough

Three independent refactors extract inlined logic into named helpers: runSnapshotCreate in snapshot.ts, hydrateMessagingConfigForRebuild in rebuild.ts, and requireProviderChoice in setup-nim-selection.ts. The snapshot test suite gains new coverage for not-live and backup-failure paths. The Biome cognitive complexity threshold is reduced from 186 to 184.

Changes

Snapshot Create Helper Extraction

Layer / File(s)	Summary
runSnapshotCreate helper and shields comment src/lib/actions/sandbox/snapshot.ts	Extracts snapshot creation into runSnapshotCreate: validates live gateway, enforces shields-down via isSnapshotCreationAllowedByShields (now documented as a permanent fail-closed boundary), calls backupSandboxState, and prints success or detailed failure output before aborting. The create branch of runSandboxSnapshot now delegates to this helper.
Snapshot test harness and new create-path tests src/lib/actions/sandbox/snapshot.test.ts	Adds hoisted shieldsMock with getter-based isShieldsDown export and findBackupMock; expands shared beforeEach for shields, openshell, dockerInspect, and findBackup; adjusts the shields-unavailable test; adds tests asserting refusal when sandbox is not live and backup-failure detail logging.
Biome complexity threshold biome.json	Decreases maxAllowedComplexity from 186 to 184 to reflect reduced function complexity after helper extractions.

Rebuild Messaging Config Hydration Extraction

Layer / File(s)	Summary
hydrateMessagingConfigForRebuild helper src/lib/actions/sandbox/rebuild.ts	Adds hydrateMessagingConfigForRebuild(sandboxName, log) that loads and hydrates stored messaging channel config and logs hydrated keys when present; replaces the inlined block in rebuildSandbox with a single call.

Provider Choice Guard for Onboarding

Layer / File(s)	Summary
requireProviderChoice helper and onboard.ts wiring src/lib/onboard/setup-nim-selection.ts, src/lib/onboard.ts	Introduces exported requireProviderChoice<T extends ProviderChoice>(selected: T | undefined): T that logs an error and calls process.exit(1) when selected is undefined; onboard.ts replaces its inline null-check with a single call to this helper.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#5481: Both PRs modify src/lib/actions/sandbox/snapshot.test.ts to extend snapshot command coverage by wiring isShieldsDown gating and adding snapshot create-related test behaviors.
• NVIDIA/NemoClaw#5428: Both PRs extract helpers from rebuildSandbox in rebuild.ts and adjust the Biome noExcessiveCognitiveComplexity threshold in biome.json, sharing touched files.
• NVIDIA/NemoClaw#5175: Both PRs modify the inference-provider selection control flow in src/lib/onboard.ts where requireProviderChoice is now wired in.

Suggested labels

refactor, area: sandbox, area: cli, area: onboarding

Poem

🐇 Hop, hop — I pulled tangled vines apart,
Each helper now lives in its own little cart.
requireProviderChoice stands guard at the gate,
runSnapshotCreate runs tidy and straight.
The threshold drops two, complexity tamed,
Clean code is the burrow where rabbits are named! 🥕

🚥 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 accurately summarizes the primary change: lowering the cognitive complexity threshold in biome.json from 186 to 184, which is the most important change from the developer's perspective.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 ratchet/185-snapshot-onboard-tie

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the ratchet/185-snapshot... branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	ratchet/185-snapshot... 0e2b7e7	+/-
nemoclaw/src/se...cret-scanner.ts	—	100%	—
nemoclaw/src/commands/slash.ts	—	100%	—
nemoclaw/src/li...bprocess-env.ts	—	100%	—
nemoclaw/src/bl...eprint/state.ts	—	98%	—
nemoclaw/src/onboard/config.ts	—	98%	—
nemoclaw/src/bl...int/snapshot.ts	—	97%	—
nemoclaw/src/bl...print/runner.ts	—	95%	—
nemoclaw/src/co...ration-state.ts	—	94%	—
nemoclaw/src/bl...ate-networks.ts	—	94%	—
nemoclaw/src/index.ts	—	94%	—

TypeScript / code-coverage/cli

The overall coverage in the ratchet/185-snapshot... branch is 46%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	ratchet/185-snapshot... 0e2b7e7	+/-
src/lib/state/o...oard-session.ts	—	90%	—
src/lib/inference/local.ts	—	76%	—
src/lib/sandbox/config.ts	—	72%	—
src/lib/onboard/preflight.ts	—	64%	—
src/lib/actions...dbox/rebuild.ts	—	62%	—
src/lib/actions...licy-channel.ts	—	56%	—
src/lib/state/sandbox.ts	—	55%	—
src/lib/policy/index.ts	—	49%	—
src/lib/onboard...er-gpu-patch.ts	—	44%	—
src/lib/onboard.ts	—	17%	—

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: snapshot-commands-e2e, rebuild-openclaw-e2e, cloud-onboard-e2e
Optional E2E: onboard-negative-paths-e2e, state-backup-restore-e2e, channels-add-remove-e2e, rebuild-hermes-e2e

Dispatch hint: snapshot-commands-e2e,rebuild-openclaw-e2e,cloud-onboard-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• snapshot-commands-e2e (medium): Directly exercises the changed snapshot command lifecycle: install/onboard, snapshot create/list/restore, backup directory handling, and credential-leak checks against a real sandbox.
• rebuild-openclaw-e2e (high): Directly covers the changed rebuild path for a live OpenClaw sandbox, including backup/restore preservation, registry/session metadata, policy persistence, config regeneration, and credential safety.
• cloud-onboard-e2e (high): Covers the modified setupNim onboarding/provider-selection path in the main non-interactive install/onboard flow with hosted inference and a real sandbox health/security check.

Optional E2E

• onboard-negative-paths-e2e (medium): Useful adjacent confidence for onboarding/provider-selection error handling and non-interactive validation paths after extracting requireProviderChoice, but the diff appears behavior-preserving and unit coverage exists.
• state-backup-restore-e2e (medium): Adjacent lifecycle coverage for backup/restore behavior shared conceptually with snapshots; useful if maintainers want extra assurance around backup side effects, but snapshot-commands-e2e is the direct coverage.
• channels-add-remove-e2e (high): Optional confidence for messaging channel configuration and gateway-credential reuse across rebuild, adjacent to the rebuild messaging config hydration code touched in this PR.
• rebuild-hermes-e2e (high): The rebuild implementation is shared enough that Hermes rebuild smoke is useful, but the changed messaging manifest reapply/hydration path is primarily OpenClaw-oriented and rebuild-openclaw-e2e is the merge-blocking choice.

New E2E recommendations

• sandbox snapshot negative paths (medium): Existing snapshot-commands-e2e covers the happy create/list/restore path, but not fail-closed snapshot creation when the sandbox is registered but not live or when shields verification cannot be performed. The PR adds unit coverage, but a future live scenario would protect the real OpenShell/gateway boundary.
  • Suggested test: Add a live snapshot negative-path E2E that creates a sandbox, stops/deletes the live sandbox while preserving local metadata, then verifies nemoclaw <name> snapshot create refuses before backup and emits the expected guidance.

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: snapshot-commands-e2e,rebuild-openclaw-e2e,cloud-onboard-e2e

[github-actions]

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: ubuntu-repo-cloud-openclaw, sandbox-rebuild-vitest, state-backup-restore-vitest
Optional Vitest E2E scenarios: double-onboard-vitest

Dispatch required Vitest E2E scenarios:

• gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw
• gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=sandbox-rebuild-vitest
• gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=state-backup-restore-vitest

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

• ubuntu-repo-cloud-openclaw: The onboarding changes move the provider-choice fail-closed path into setup-nim-selection and call it from setupNim. The live-supported cloud OpenClaw registry scenario exercises the normal non-interactive onboarding path through provider selection and inference setup.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw
• sandbox-rebuild-vitest: src/lib/actions/sandbox/rebuild.ts changed the rebuild pre-destructive messaging-config hydration path. The discrete sandbox rebuild Vitest job is the focused live coverage for real sandbox rebuild behavior.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=sandbox-rebuild-vitest
• state-backup-restore-vitest: src/lib/actions/sandbox/snapshot.ts refactors snapshot creation, liveness gating, shields gating, and backup failure reporting. The state backup/restore live Vitest job is the smallest wired job that exercises snapshot/backup state behavior against a live sandbox.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=state-backup-restore-vitest

Optional Vitest E2E scenarios

• double-onboard-vitest: Adjacent coverage for repeated/custom-provider onboarding plus stale-registry rebuild recovery; useful because this PR touches both provider selection and rebuild, but it is broader than the primary changed surfaces.
  • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=double-onboard-vitest

Relevant changed files

• src/lib/actions/sandbox/rebuild.ts
• src/lib/actions/sandbox/snapshot.ts
• src/lib/onboard.ts
• src/lib/onboard/setup-nim-selection.ts

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Since last review: 0 prior items resolved, 0 still apply, 0 new items found

Consider writing more tests for

• **Runtime validation** — Add a focused unit test for `requireProviderChoice(undefined)` that asserts it prints `No provider was selected.` and exits with code 1, plus a positive case showing `requireProviderChoice({ key: "ollama" })` returns the same object without exiting.. The changed code touches sandbox snapshot creation, rebuild preparation, onboarding provider selection, and lint ratcheting. Added snapshot tests cover the highest-risk create-path behavior, but small focused tests would further lock down the extracted provider guard and rebuild hydration sequencing.
• **Runtime validation** — Add a rebuild-path unit test showing messaging config hydration runs before confirmation, credential preflight, backup/delete/recreate work, and verbose logging includes only hydrated config keys.. The changed code touches sandbox snapshot creation, rebuild preparation, onboarding provider selection, and lint ratcheting. Added snapshot tests cover the highest-risk create-path behavior, but small focused tests would further lock down the extracted provider guard and rebuild hydration sequencing.
• **Runtime validation** — Strengthen the snapshot create success-path test to assert the live sandbox lookup and `isShieldsDown("alpha")` gate happen before `backupSandboxState("alpha", { name: "before-upgrade" })`.. The changed code touches sandbox snapshot creation, rebuild preparation, onboarding provider selection, and lint ratcheting. Added snapshot tests cover the highest-risk create-path behavior, but small focused tests would further lock down the extracted provider guard and rebuild hydration sequencing.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

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