Skip to content

fix(doctor): warn on incomplete lifecycle registration#7406

Merged
apurvvkumaria merged 7 commits into
NVIDIA:mainfrom
scarab-systems:scarab-systems/nemoclaw-7387-doctor-lifecycle-registration
Jul 25, 2026
Merged

fix(doctor): warn on incomplete lifecycle registration#7406
apurvvkumaria merged 7 commits into
NVIDIA:mainfrom
scarab-systems:scarab-systems/nemoclaw-7387-doctor-lifecycle-registration

Conversation

@scarab-systems

@scarab-systems scarab-systems commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Summary

  • add a read-only doctor check for registered sandbox lifecycle metadata used by snapshot, rebuild, recovery, and related flows
  • warn when a registry entry is incomplete even if runtime health probes are otherwise readable
  • report only missing or invalid metadata field names, without returning registry values or captured runtime output

Fixes #7387.

Validation

  • npm run build:cli
  • npm run typecheck:cli
  • npx vitest run --project cli src/lib/actions/sandbox/doctor-lifecycle-registration.test.ts src/lib/actions/sandbox/doctor-flow.test.ts
  • npm run test:changed
  • npm run check:diff

No credentialed or live Brev environment was used for this PR.

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 (preflight, runner, or sandbox)
  • Sensitive-path review completed — the check is read-only, reports field names without stored values, and refuses to probe or recover from an invalid registered gateway binding.

Documentation Writer Review

  • Documentation writer subagent reviewed the completed changes
  • Result: docs-updated
  • Evidence: docs/reference/commands.mdx; generated OpenClaw, Hermes, and Deep Agents variants contain the lifecycle-readiness and invalid-binding behavior. Focused lifecycle tests (24), the CI-reproduced gateway-token integration tests (12), the expanded doctor suites (31), CLI/plugin builds, CLI type-checking, normal hooks, and npm run docs passed. The final fixture-only commit did not change docs inputs.
  • 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
  • Focused lifecycle-registration and doctor-flow tests pass: 24 passed
  • CI-reproduced gateway-token integration tests pass: 12 passed; expanded doctor suites pass: 31 passed
  • Quality gates are complete and no secrets or credentials were committed
  • npm run docs passed with 0 errors

Signed-off-by: ScarabSystems scarab.systems@yahoo.com

Disclosure: This PR was prepared with AI assistance under human direction and review.

Summary by CodeRabbit

  • New Features
    • Enhanced the sandbox doctor report to validate lifecycle registration metadata for snapshot/rebuild/upgrade/recovery/reboot, including durable dashboard/gateway port requirements and actionable guidance to re-register/re-onboard when incomplete or invalid.
  • Bug Fixes
    • Improved behavior when a registered gateway binding can’t be resolved: doctor reports the failure and skips gateway probing/recovery selection.
  • Documentation
    • Updated the doctor command reference to cover lifecycle validation and dashboard scoping.
  • Tests
    • Expanded lifecycle-registration diagnostics coverage and updated doctor-flow expectations; added doctor-specific sandbox registry test helpers.

Advisor infrastructure waiver

The secondary Nemotron advisor timed out during final synthesis after completing an empty finding ledger, all nine security categories as PASS, and a reconciliation verdict that the PR is safe to merge. The primary Terra advisor passed, the published review has no actionable finding, and no review thread is unresolved. Maintainer review accepts this as an advisor infrastructure timeout, not a code failure.

Signed-off-by: ScarabSystems <scarab.systems@yahoo.com>
@copy-pr-bot

copy-pr-bot Bot commented Jul 23, 2026

Copy link
Copy Markdown

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

coderabbitai Bot commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

The sandbox doctor now validates lifecycle-registration metadata and gateway bindings, reports incomplete or invalid states, integrates these checks into doctor output, documents the behavior, and adds focused and end-to-end test coverage.

Changes

Sandbox lifecycle registration diagnostics

Layer / File(s) Summary
Lifecycle metadata validation
src/lib/domain/lifecycle-registration.ts, src/lib/actions/sandbox/doctor-lifecycle-registration.ts
Validates lifecycle fields, image provenance, and durable ports, then returns ok or warn checks with affected operations and re-registration guidance.
Doctor report and gateway integration
src/lib/actions/sandbox/doctor.ts
Adds lifecycle checks for registered sandboxes, conditionally requires dashboard metadata, and reports invalid gateway bindings without probing live gateways.
Lifecycle and doctor flow coverage
src/lib/actions/sandbox/doctor-lifecycle-registration.test.ts, src/lib/actions/sandbox/doctor-flow.test.ts, test/cli/helpers.ts, test/cli/doctor-gateway-token.test.ts, docs/reference/commands.mdx
Covers complete and incomplete registrations, invalid metadata, terminal agents, JSON output, gateway failures, doctor fixtures, and documented behavior.

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

Sequence Diagram(s)

sequenceDiagram
  participant NemoClawCLI
  participant runSandboxDoctor
  participant resolveSandboxGatewayName
  participant collectDoctorChecks
  participant buildLifecycleRegistrationCheck
  participant collectLifecycleRegistrationIssues
  NemoClawCLI->>runSandboxDoctor: request doctor report
  runSandboxDoctor->>resolveSandboxGatewayName: resolve registered gateway binding
  resolveSandboxGatewayName-->>runSandboxDoctor: gateway name or failure
  runSandboxDoctor->>collectDoctorChecks: pass nullable gateway name
  collectDoctorChecks->>buildLifecycleRegistrationCheck: pass registered sandbox metadata
  buildLifecycleRegistrationCheck->>collectLifecycleRegistrationIssues: validate lifecycle fields
  collectLifecycleRegistrationIssues-->>buildLifecycleRegistrationCheck: issues or no issues
  buildLifecycleRegistrationCheck-->>collectDoctorChecks: lifecycle check status
  collectDoctorChecks-->>runSandboxDoctor: gateway and sandbox checks
  runSandboxDoctor-->>NemoClawCLI: render doctor report
Loading

Suggested labels: feature

Suggested reviewers: cv, ericksoa, sandl99

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The PR implements the lifecycle-registration doctor check, required field validation, remediation hints, and test coverage requested by #7387.
Out of Scope Changes check ✅ Passed The file changes are limited to the doctor check, its tests, and docs/helpers, with no obvious unrelated scope creep.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: adding a doctor warning for incomplete lifecycle registration.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/actions/sandbox/doctor-lifecycle-registration.ts`:
- Around line 78-86: The lifecycle validation around hasCustomImageEvidence and
hasManagedImageEvidence currently reports the same blank nemoclawVersion as both
invalid and missing. Ensure the missing-issue branch only runs when no invalid
issue was added for that field, while preserving the existing invalid
classification for blank or otherwise invalid values and the missing
classification when metadata is truly absent.
🪄 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: 5d26c25d-4823-4fd8-805b-f1c16eac6537

📥 Commits

Reviewing files that changed from the base of the PR and between d13e34a and 0640320.

📒 Files selected for processing (4)
  • src/lib/actions/sandbox/doctor-flow.test.ts
  • src/lib/actions/sandbox/doctor-lifecycle-registration.test.ts
  • src/lib/actions/sandbox/doctor-lifecycle-registration.ts
  • src/lib/actions/sandbox/doctor.ts

Comment thread src/lib/actions/sandbox/doctor-lifecycle-registration.ts Outdated
@github-actions

github-actions Bot commented Jul 23, 2026

Copy link
Copy Markdown
Contributor

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): Failed

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: onboard-repair, onboard-resume

1 optional E2E recommendation
  • staging-brev-launchable

Workflow run details

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
src/lib/actions/sandbox/doctor-lifecycle-registration.ts (1)

71-71: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add public-boundary coverage for invalid gatewayName.

The new gatewayName validation is not exercised by the added tests. Add a buildLifecycleRegistrationCheck(..., sandbox({ gatewayName: " " }), ...) case asserting warn and invalid gatewayName.

As per path instructions, tests should prove observable behavior through the public boundary.

🤖 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/actions/sandbox/doctor-lifecycle-registration.ts` at line 71, Add a
public-boundary test in the lifecycle registration checks using
buildLifecycleRegistrationCheck with sandbox({ gatewayName: " " }); assert that
the result has warn severity and reports “invalid gatewayName.”

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 `@src/lib/actions/sandbox/doctor-lifecycle-registration.ts`:
- Around line 70-75: Move the pure lifecycle validation policy surrounding
addPresenceIssue, hasCustomImageEvidence, and the field validators into a
domain-layer module under src/lib/domain, preserving the existing mappings and
issue-collection behavior. Update doctor-lifecycle-registration.ts to call the
domain policy while retaining only doctor-specific orchestration and formatting
in the action module.

---

Nitpick comments:
In `@src/lib/actions/sandbox/doctor-lifecycle-registration.ts`:
- Line 71: Add a public-boundary test in the lifecycle registration checks using
buildLifecycleRegistrationCheck with sandbox({ gatewayName: " " }); assert that
the result has warn severity and reports “invalid gatewayName.”
🪄 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: c4c93f36-7871-4b12-8825-c1dfcdbae172

📥 Commits

Reviewing files that changed from the base of the PR and between 0640320 and 9d9d132.

📒 Files selected for processing (3)
  • src/lib/actions/sandbox/doctor-flow.test.ts
  • src/lib/actions/sandbox/doctor-lifecycle-registration.test.ts
  • src/lib/actions/sandbox/doctor-lifecycle-registration.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • src/lib/actions/sandbox/doctor-flow.test.ts

Comment thread src/lib/actions/sandbox/doctor-lifecycle-registration.ts Outdated
@wscurran wscurran added area: cli Command line interface, flags, terminal UX, or output area: sandbox OpenShell sandbox lifecycle, runtime, config, or recovery bug-fix PR fixes a bug or regression labels Jul 23, 2026
@wscurran

Copy link
Copy Markdown
Contributor

✨ Thanks for the PR. This adds a read-only doctor check for incomplete sandbox lifecycle registration metadata. Maintainers will review the validation logic and CLI integration.


Related open issues:


Related open issues:

@prekshivyas prekshivyas self-assigned this Jul 25, 2026

@prekshivyas prekshivyas left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at 6bc39b7. Lifecycle validation is read-only and redacted; invalid gateway bindings do not trigger probes against the wrong gateway. The CI-reproduced fixture gap is fixed and focused suites pass. Required E2E remains independently enforced.

@prekshivyas prekshivyas added the v0.0.96 Release target label Jul 25, 2026
@apurvvkumaria
apurvvkumaria merged commit f695980 into NVIDIA:main Jul 25, 2026
115 of 122 checks passed
@scarab-systems
scarab-systems deleted the scarab-systems/nemoclaw-7387-doctor-lifecycle-registration branch July 25, 2026 11:53
scarab-systems added a commit to scarab-systems/scarab-field-lab that referenced this pull request Jul 25, 2026
Record NVIDIA/NemoClaw#7406 as an accepted #7387 repair after upstream merge.

Refresh NVIDIA/NemoClaw#7254 as accepted test coverage for #6042 while noting the issue remains open and the merged PR was test-only.

Refresh NVIDIA/NemoClaw#7291/#7273 as closed without merge so the Field Lab no longer reports that PR as open.

Verification: gh pr/issue views for #7254, #7406, #7291, #6042, #7387, and #7273; git diff --cached --check; public leakage scan for local/private/SDS terms.
@scarab-systems

Copy link
Copy Markdown
Contributor Author

Woohoo! Thank You! very glad to help. 🙏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: cli Command line interface, flags, terminal UX, or output area: sandbox OpenShell sandbox lifecycle, runtime, config, or recovery bug-fix PR fixes a bug or regression v0.0.96 Release target

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Brev][doctor] Detect registry entries incomplete for snapshot and rebuild

4 participants