refactor(rebuild): lower cognitive complexity ratchet to 224

[cv]

Summary

Continue the stacked cognitive-complexity ratchet by lowering the threshold from 225 to 224. This trims the rebuild hotspot with small guard/preflight extractions.

Changes

• Lowered complexity/noExcessiveCognitiveComplexity from 225 to 224 in biome.json.
• Extracted registry-entry lookup and OpenShell gateway schema preflight guards from rebuildSandbox.
• Preserved missing-registry and gateway-schema-mismatch failure behavior while reducing rebuildSandbox complexity below the new ceiling.

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/rebuild-credential-preflight.test.ts test/rebuild-stale-recovery.test.ts src/lib/actions/sandbox/rebuild-gateway-drift.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

• Refactor

  • Refactored sandbox rebuild logic to improve code organization and error handling through helper functions.

• Chores

  • Updated code quality linter configuration.

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

📝 Walkthrough

Walkthrough

rebuildSandbox in rebuild.ts is refactored by introducing a local RebuildSandboxEntry type and two helper functions—getRebuildSandboxEntryOrBail and checkRebuildGatewaySchemaPreflight—replacing previously inline registry lookup and gateway schema mismatch logic. The Biome linter's noExcessiveCognitiveComplexity.maxAllowedComplexity is reduced from 225 to 224.

Changes

rebuildSandbox preflight refactor

Layer / File(s)	Summary
RebuildSandboxEntry type and preflight helpers src/lib/actions/sandbox/rebuild.ts	Adds a local RebuildSandboxEntry type alias extending registry.SandboxEntry with an optional agents field, and introduces getRebuildSandboxEntryOrBail() (registry lookup with bail-on-missing) and checkRebuildGatewaySchemaPreflight() (OpenShell gateway schema mismatch detection with standardized bail messaging).
Call-site updates and complexity threshold src/lib/actions/sandbox/rebuild.ts, biome.json	Replaces inline registry lookup and inline gateway schema check in rebuildSandbox with calls to the two new helpers, and decrements noExcessiveCognitiveComplexity.maxAllowedComplexity from 225 to 224 to match the reduced function complexity.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#5426: Adjusts the same biome.json cognitive-complexity threshold and refactors rebuildSandbox in the same file by extracting a different control-flow guard into a helper.
• NVIDIA/NemoClaw#5422: Also tightens noExcessiveCognitiveComplexity and extracts preflight/control-flow logic from rebuildSandbox into helper functions.
• NVIDIA/NemoClaw#5419: Directly modifies the same biome.json maxAllowedComplexity setting as part of the same complexity ratcheting effort.

Suggested labels

refactor

🐇 Two helpers now stand guard at the gate,
No inline checks left to inflate—
The sandbox entry? Fetched with care,
The gateway schema? Checked right there.
One less complexity point to bear! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: lowering the cognitive complexity threshold in biome.json from 225 to 224, which is the primary objective and the most concrete change across the changeset.
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.

_{✏️ 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/224-rebuild-registry-guard

---

_{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/224-rebuild-... 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/224-rebuild-... d6d5bfe	+/-
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/224-rebuild-... branch is 45%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	main	ratchet/224-rebuild-... d6d5bfe	+/-
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	—	60%	—
src/lib/state/sandbox.ts	—	55%	—
src/lib/actions...licy-channel.ts	—	52%	—
src/lib/onboard...er-gpu-patch.ts	—	50%	—
src/lib/policy/index.ts	—	49%	—
src/lib/onboard.ts	—	17%	—

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Failed: Advisor SDK provider error: analysis: 403 <title>403 Forbidden</title>

403 Forbidden

[github-actions]

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: None
Optional Vitest E2E scenarios: None

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Failed: Scenario advisor SDK provider error: scenario-analysis: 403 <title>403 Forbidden</title>

403 Forbidden

[github-actions]

PR Review Advisor

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

Review findings

🛠️ Needs attention

• None.

🔎 Worth checking

• Remove stale WeChat claim or add the extraction: The PR body lists “Extracted WeChat metadata staging into `stashWechatMetadataForRebuild` while preserving sandbox-scoped leak prevention,” but the current diff only extracts registry lookup and OpenShell gateway schema preflight helpers. I did not find a `stashWechatMetadataForRebuild` helper or WeChat metadata-staging change.
  • Recommendation: Update the PR description to match this diff, or include the described WeChat metadata-staging extraction and its relevant leak-prevention evidence/tests.
  • Evidence: Changed files are only `biome.json` and `src/lib/actions/sandbox/rebuild.ts`; grep found no `stashWechatMetadataForRebuild` symbol, and the rebuild diff adds `getRebuildSandboxEntryOrBail` and `checkRebuildGatewaySchemaPreflight`.

🌱 Nice ideas

• None.

Consider writing more tests for

• **Runtime validation** — Missing registry entry exits or throws before agent lookup, gateway schema preflight, confirmation, backup, sandbox delete, or onboard recreate.. The changed code is in sandbox rebuild lifecycle logic. Existing gateway-drift tests cover the most important schema-preflight behavior, but the newly extracted registry and multi-agent guards would benefit from direct negative-path runtime validation.
• **Runtime validation** — Multi-agent registry entry exits or throws before gateway schema preflight, confirmation, backup, sandbox delete, or onboard recreate.. The changed code is in sandbox rebuild lifecycle logic. Existing gateway-drift tests cover the most important schema-preflight behavior, but the newly extracted registry and multi-agent guards would benefit from direct negative-path runtime validation.
• **Runtime validation** — Gateway schema mismatch continues printing the `nemoclaw <sandbox> rebuild` remediation command and stops before confirmation or destructive rebuild work.. The changed code is in sandbox rebuild lifecycle logic. Existing gateway-drift tests cover the most important schema-preflight behavior, but the newly extracted registry and multi-agent guards would benefit from direct negative-path runtime validation.
• **Acceptance clause:** Extracted WeChat metadata staging into `stashWechatMetadataForRebuild` while preserving sandbox-scoped leak prevention. — add test evidence or identify existing coverage. No `stashWechatMetadataForRebuild` helper or WeChat metadata-staging change appears in the current changed files.
• **Acceptance clause:** `npx @biomejs/biome lint --only=complexity/noExcessiveCognitiveComplexity --max-diagnostics=none .` — add test evidence or identify existing coverage. Listed as PR verification, but this advisory review did not execute package-manager or test commands.
• **Acceptance clause:** `npm run typecheck:cli` — add test evidence or identify existing coverage. Listed as PR verification, but this advisory review did not execute package-manager or test commands.
• **Acceptance clause:** `npx vitest run --project cli test/rebuild-credential-preflight.test.ts test/rebuild-stale-recovery.test.ts src/lib/actions/sandbox/rebuild-gateway-drift.test.ts` — add test evidence or identify existing coverage. Listed as PR verification, but this advisory review did not execute package-manager or test commands. The named rebuild/gateway test files exist.

Since last review details

Current findings:

• Remove stale WeChat claim or add the extraction: The PR body lists “Extracted WeChat metadata staging into `stashWechatMetadataForRebuild` while preserving sandbox-scoped leak prevention,” but the current diff only extracts registry lookup and OpenShell gateway schema preflight helpers. I did not find a `stashWechatMetadataForRebuild` helper or WeChat metadata-staging change.
  • Recommendation: Update the PR description to match this diff, or include the described WeChat metadata-staging extraction and its relevant leak-prevention evidence/tests.
  • Evidence: Changed files are only `biome.json` and `src/lib/actions/sandbox/rebuild.ts`; grep found no `stashWechatMetadataForRebuild` symbol, and the rebuild diff adds `getRebuildSandboxEntryOrBail` and `checkRebuildGatewaySchemaPreflight`.

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.