feat(onboard): bind external gateway lifecycle authority - #7246
Merged
Conversation
Add a versioned gateway lifecycle declaration and durable resume binding. Register the exact endpoint and fail closed across preflight and recovery. Co-authored-by: Souvik Ghosh <138186578+souvikDevloper@users.noreply.github.com> Co-authored-by: Apurv Kumaria <akumaria@nvidia.com> Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
jyaunches
added
platform: brev
Contributor
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis change adds a versioned gateway lifecycle authority contract, validates externally supervised gateways, persists authority across onboarding checkpoints, prevents destructive lifecycle actions, and integrates attachment-only behavior into onboarding, recovery, runtime, and diagnostic output. ChangesGateway lifecycle authority
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant Onboarding
participant GatewayManagement
participant GatewayHostRuntime
participant Supervisor
participant OpenShell
Onboarding->>GatewayManagement: Load and validate declaration
GatewayManagement-->>Onboarding: Resolve lifecycle owner
Onboarding->>GatewayHostRuntime: Probe attachment
GatewayHostRuntime->>Supervisor: Check unit, cgroup, and listener identity
Supervisor-->>GatewayHostRuntime: Return runtime evidence
GatewayHostRuntime->>OpenShell: Register and select exact endpoint
OpenShell-->>Onboarding: Return attached gateway
Onboarding->>Onboarding: Checkpoint authority and continue onboarding
Possibly related issues
Possibly related PRs
Suggested labels: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Contributor
|
🌿 Preview your docs: https://nvidia-preview-pr-7246.docs.buildwithfern.com/nemoclaw |
Contributor
Code Coverage OverviewLanguages: TypeScript TypeScript / code-coverage/pluginThe overall coverage in commit bcbbef7 in the TypeScript / code-coverage/cliThe overall coverage in commit bcbbef7 in the Show a code coverage summary of the most impacted files.
Updated |
Contributor
PR Review Advisor — InformationalAdvisor assessment: Informational / high confidence Model lanes
Nemotron output stays in workflow artifacts and does not change the assessment above. E2E guidanceAdvisory only. E2E / PR Gate selects and runs jobs independently. Recommended E2E: 1 optional E2E recommendation
This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
src/lib/onboard/gateway-ownership.ts (1)
237-238: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueDoc comment overstates what
listenerPidscontains. The externally-supervised probe path feeds this field fromgetGatewayPortListenerRawScan(unfiltered enumeration), not identity-verified gateways — seeprobeGatewayAttachmentingateway-host-runtime.ts, which setslistenerPids: scan.pidsfrom the raw scan. That is intentional and load-bearing: themultiple_ownerscheck at Line 336 must count every listener (e.g. SO_REUSEPORT) to fail closed. The current wording could lead a future maintainer to add identity filtering upstream and silently weaken that guarantee. Consider clarifying the comment to "All processes holding the port; identity is established separately below."🤖 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/gateway-ownership.ts` around lines 237 - 238, Update the doc comment for listenerPids in the gateway ownership model to state that it contains all processes holding the port, including unfiltered listeners, and that identity is established separately. Do not change the raw scan flow or the multiple_owners counting behavior.
🤖 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/gateway-authority-checkpoint.test.ts`:
- Around line 61-69: Update the round-trip test “accepts the same authority
after a process resume round-trip (`#6576`)” so it distinguishes a persisted
checkpoint from a reset one, rather than only comparing the returned owner.
Assert an observable outcome specific to the already-recorded branch of
bindGatewayAuthorityToCheckpoint, while retaining the existing same-owner resume
scenario.
In `@src/lib/onboard/gateway-host-runtime.ts`:
- Around line 186-195: The listener identity check in probeGatewayAttachment
must close the PID-reuse gap between reading /proc/<pid>/exe and
/proc/<pid>/cgroup. Revalidate that the PID still represents the originally
scanned listener before accepting its supervisor match, or combine the
executable and cgroup identity reads into one consistent probe; update
readListenerSupervisorMatch or the surrounding probe flow while preserving the
existing attach-gate behavior.
In `@src/lib/state/onboard-checkpoint.ts`:
- Around line 4-9: Move SUPPORTED_GATEWAY_CAPABILITIES out of the onboard layer
into a shared core/domain module such as ports.ts or a dedicated
gateway-capabilities module, then update onboard-checkpoint.ts and
gateway-management.ts to import it from there. Re-export it from
gateway-management.ts to preserve existing onboard callers, while ensuring the
shared module becomes the single source of truth and the state layer no longer
imports ../onboard/gateway-management.
---
Nitpick comments:
In `@src/lib/onboard/gateway-ownership.ts`:
- Around line 237-238: Update the doc comment for listenerPids in the gateway
ownership model to state that it contains all processes holding the port,
including unfiltered listeners, and that identity is established separately. Do
not change the raw scan flow or the multiple_owners counting behavior.
🪄 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: 2b375967-eb1f-4218-93a0-a307c5443b57
📒 Files selected for processing (45)
docs/deployment/gateway-lifecycle-authority.mdxdocs/index.ymlsrc/lib/onboard.tssrc/lib/onboard/checkpoint-replay.test.tssrc/lib/onboard/checkpoint-resume-guard.test.tssrc/lib/onboard/dashboard-preflight-ports.test.tssrc/lib/onboard/docker-driver-gateway-port-listener.test.tssrc/lib/onboard/docker-driver-gateway-port-listener.tssrc/lib/onboard/docker-driver-gateway-runtime.tssrc/lib/onboard/gateway-authority-checkpoint.test.tssrc/lib/onboard/gateway-authority-checkpoint.tssrc/lib/onboard/gateway-host-runtime-https.test.tssrc/lib/onboard/gateway-host-runtime.test.tssrc/lib/onboard/gateway-host-runtime.tssrc/lib/onboard/gateway-management.test.tssrc/lib/onboard/gateway-management.tssrc/lib/onboard/gateway-ownership.test.tssrc/lib/onboard/gateway-ownership.tssrc/lib/onboard/gateway-port-conflict.test.tssrc/lib/onboard/gateway-port-conflict.tssrc/lib/onboard/gateway-recovery.test.tssrc/lib/onboard/gateway-recovery.tssrc/lib/onboard/gateway-stale-port-reuse.test.tssrc/lib/onboard/gateway-stale-port-reuse.tssrc/lib/onboard/machine/handlers/gateway.test.tssrc/lib/onboard/machine/handlers/gateway.tssrc/lib/onboard/machine/handlers/sandbox-checkpoint-crash-recovery.test.tssrc/lib/onboard/machine/handlers/sandbox-messaging.test.tssrc/lib/onboard/machine/handlers/sandbox.test.tssrc/lib/onboard/machine/initial-flow-phases.test.tssrc/lib/onboard/preflight-gateway-cleanup-decision.test.tssrc/lib/onboard/preflight-gateway-cleanup-decision.tssrc/lib/onboard/preflight-gateway-reuse.test.tssrc/lib/onboard/preflight-gateway-reuse.tssrc/lib/onboard/preflight-gateway-sequence.test.tssrc/lib/onboard/preflight-gateway-sequence.tssrc/lib/onboard/preflight-orphan-gateway-cleanup.test.tssrc/lib/onboard/preflight-orphan-gateway-cleanup.tssrc/lib/onboard/preflight-ports.tssrc/lib/onboard/session-bootstrap.test.tssrc/lib/state/onboard-checkpoint-migrate.test.tssrc/lib/state/onboard-checkpoint-migrate.tssrc/lib/state/onboard-checkpoint-types.tssrc/lib/state/onboard-checkpoint.test.tssrc/lib/state/onboard-checkpoint.ts
This was referenced Jul 21, 2026
Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/lib/onboard/gateway-host-runtime.ts (1)
353-358: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick winBind the owner before mutating OpenShell.
attachGatewaytrusts itsownerparameter without comparing it togetGatewayOwner(). A stale resumed owner can therefore register/select its endpoint after the declaration resolves to a different authority. CallbindGatewayOwner(owner)before the early return and before any OpenShell command; add a test proving mismatches fail without registration.Proposed fix
async function attachGateway( owner: GatewayOwner, expectedProbe: GatewayAttachmentProbe, ): Promise<void> { + bindGatewayOwner(owner); if (!isExternallySupervised(owner) || !owner.endpoint) return;As per path instructions, in-scope callers must use one authoritative path.
🤖 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/gateway-host-runtime.ts` around lines 353 - 358, Update attachGateway to call bindGatewayOwner(owner) as its first operation, before the supervision/endpoint early return and any OpenShell mutation. Ensure mismatched owners fail immediately without registering or selecting an endpoint, and add a test covering this rejection and absence of registration.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.
Outside diff comments:
In `@src/lib/onboard/gateway-host-runtime.ts`:
- Around line 353-358: Update attachGateway to call bindGatewayOwner(owner) as
its first operation, before the supervision/endpoint early return and any
OpenShell mutation. Ensure mismatched owners fail immediately without
registering or selecting an endpoint, and add a test covering this rejection and
absence of registration.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: edc6f847-f11e-4d6e-a07e-bb281e13a7ca
📒 Files selected for processing (8)
src/lib/onboard/gateway-host-runtime.test.tssrc/lib/onboard/gateway-host-runtime.tssrc/lib/onboard/gateway-management.test.tssrc/lib/onboard/gateway-management.tssrc/lib/onboard/gateway-ownership.test.tssrc/lib/onboard/gateway-ownership.tssrc/lib/onboard/machine/handlers/gateway.test.tssrc/lib/onboard/machine/initial-flow-phases.test.ts
🚧 Files skipped from review as they are similar to previous changes (7)
- src/lib/onboard/gateway-management.test.ts
- src/lib/onboard/machine/initial-flow-phases.test.ts
- src/lib/onboard/gateway-host-runtime.test.ts
- src/lib/onboard/gateway-management.ts
- src/lib/onboard/gateway-ownership.test.ts
- src/lib/onboard/machine/handlers/gateway.test.ts
- src/lib/onboard/gateway-ownership.ts
Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
prekshivyas
approved these changes
Jul 24, 2026
Collaborator
|
Exact-head sensitive-path re-review for This review carries forward the complete 68-file security review and re-read the exact six-file delta in this SHA.
No findings. Delta files reviewed: Local exact-head evidence: focused tests 11/11 passed; |
Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>
Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>
Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>
Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>
Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>
Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>
jyaunches
dismissed
apurvvkumaria’s stale review
July 24, 2026 12:33
Stale after the blocking teardown-authority gap was fixed in 57ebaf7 and covered by zero-effect tests for stop, final-sandbox cleanup, scoped uninstall, and full uninstall for both systemd supervisor kinds. Issue #6576 now records the accepted design. Current head bcbbef7 is current with main and has green required CI, selected live E2E, CodeRabbit, and both advisor lanes. Apurv remains requested for current-head review.
23 tasks
senthilr-nv
added a commit
that referenced
this pull request
Jul 25, 2026
<!-- markdownlint-disable MD041 --> ## Summary Adds the canonical pre-tag `## v0.0.95` release entry to `docs/changelog/2026-07-24.mdx`, before the existing v0.0.94 entry. The entry summarizes approved user-visible changes merged since v0.0.94 and excludes internal-only prerequisites. ## Changes - Adds the v0.0.95 summary and detailed bullets for gateway lifecycle, recovery, state transfer, inference compatibility, sandbox security, Discord policy, and E2E evidence. - Links each user-facing theme to the most specific published documentation. - Records the release entry in the shared native changelog used by the OpenClaw, Hermes, and Deep Agents guides. Source summary: - [#7246](#7246), [#7228](#7228), [#7267](#7267), [#7489](#7489), [#7509](#7509), [#7351](#7351), and [#7290](#7290) -> `docs/changelog/2026-07-24.mdx`: Gateway authority, forward teardown and retry, managed recovery, Hermes restart recovery, scoped uninstall, and orphan-aware backup behavior. - [#7344](#7344) and [#7416](#7416) -> `docs/changelog/2026-07-24.mdx`: Atomic SQLite restore and host download verification. - [#7476](#7476), [#7347](#7347), [#7281](#7281), [#7485](#7485), [#7491](#7491), and [#7422](#7422) -> `docs/changelog/2026-07-24.mdx`: Windows Ollama reuse, CDI fallback, bounded OpenRouter connection setup, Nemotron-3 request compatibility, and managed Deep Agents retry and provider-error behavior. - [#6884](#6884), [#7481](#7481), [#6878](#6878), [#7467](#7467), [#7502](#7502), [#7503](#7503), [#7504](#7504), and [#7486](#7486) -> `docs/changelog/2026-07-24.mdx`: Trusted base-image overrides, local rebuild images, runtime validation, config preservation, reviewed package updates, and fewer final-image payload layers. - [#7303](#7303) -> `docs/changelog/2026-07-24.mdx`: Scoped Discord application-command management. - [#7488](#7488), [#7465](#7465), [#7497](#7497), [#7464](#7464), [#7501](#7501), [#7494](#7494), and [#7493](#7493) -> `docs/changelog/2026-07-24.mdx`: Selected-test risk signals, retry cleanup, full root-image validation, direct-main Hermes setup, executed PR-gate evidence, nightly history, and runner wait reporting. - [#7447](#7447) is an internal pinned-runtime prerequisite and is intentionally excluded from canonical supported-integration documentation. - [#7370](#7370) adds maintainer-only advisory reconciliation tooling and does not change supported user behavior. - [#7495](#7495) updates existing documentation and does not add a new v0.0.95 behavior claim. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [ ] Code change with doc updates - [x] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates - [ ] Tests added or updated for changed behavior - [x] Existing tests cover changed behavior — justification: `test/changelog-docs.test.ts` validates the dated changelog structure, heading uniqueness, and published links. - [ ] Tests not applicable — justification: - [x] 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: - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Documentation Writer Review - [x] Documentation writer subagent reviewed the completed changes - Result: `docs-updated` - Evidence: `docs/changelog/2026-07-24.mdx`; writing rules, documentation style, factual release meaning, and published links reviewed at exact head `58b02f2bf`. - Agent: Codex documentation writer reviewer <!-- docs-review-head-sha: 58b02f2 --> <!-- docs-review-agents-blob-sha: 9c9b36d --> ## DGX Station Hardware Evidence - [ ] Tested on DGX Station - Tested commit: - Station profile/scenario: - Result: - Supporting evidence: ## Verification - [x] PR description includes a `Signed-off-by:` line and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: `npx vitest run test/changelog-docs.test.ts` passed 6 tests. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — the build passed with 0 errors and 2 Fern warnings. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) --- Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a new v0.0.95 changelog entry above v0.0.94. * Documented improved externally supervised gateway lifecycle ownership. * Improved snapshot restore reliability and SQLite state handling. * Tightened CLI `backup-all` behavior and host artifact verification. * Updated Windows onboarding guidance (including Ollama service reuse and CDI directory fallback). * Noted inference compatibility fixes, deeper agent failure classification, stricter base-image validation, updated Discord bot command permissions, and refined E2E release automation evidence handling. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com>
23 tasks
senthilr-nv
added a commit
that referenced
this pull request
Jul 25, 2026
<!-- markdownlint-disable MD041 --> ## Summary NemoClaw now gives its default OpenShell gateway on port `8080` an explicit host-service owner: a validated systemd user service on Linux or the official Homebrew service on Apple Silicon. NemoClaw-managed custom ports retain the detached-process lifecycle, while a declared external supervisor retains authority on any matching port. ## Related Issue Fixes #6903 ## Product Scope **Verdict: PASS.** Issue #6903 contains the member-authored lifecycle, ownership, compatibility, security, and validation decision for the managed default gateway, and the decision is incorporated into the #7209 release-validation tracker. The refreshed implementation also preserves main's separately accepted external-supervisor contract from #7246. This product-scope verdict is based on those design records. It is separate from, and does not infer approval from, GitHub's `mergeStateStatus`. ## Changes - Implement the #6903 managed-service design for the default gateway port. - Validate systemd and Homebrew service identity, executable paths, listeners, TLS/auth configuration, health, and XDG-managed environment state before changing lifecycle ownership. - Stage but do not start NemoClaw's marked Linux user unit during install; onboarding selects and starts it only after configuration and port ownership are valid. - Preserve detached-process behavior for NemoClaw-managed custom ports and platforms without the selected service manager. - Preserve main's externally supervised lifecycle authority on both default and custom ports. - Keep installer staging, runtime service identity, and reboot recovery aligned with absolute `XDG_BIN_HOME` and `XDG_CONFIG_HOME` values, while retaining their default paths. - Remove only NemoClaw-owned service and environment state during managed uninstall while preserving upstream, Homebrew, and externally supervised resources. - Add focused unit, installer, uninstall, lifecycle, reboot-recovery, adversarial-file, and documentation-contract coverage. - Update platform, command, architecture, uninstall, and troubleshooting documentation. The service-selection path is required by #6903 so reboot ownership is explicit. Starting another detached process cannot provide that contract; the gateway service, installer service, uninstall, and lifecycle suites protect the selection and ownership boundaries. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [x] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates - [x] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [ ] Tests not applicable — justification: - [x] Docs updated for user-facing behavior changes - [ ] Docs not applicable — justification: - [x] 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: [automated exact-head nine-category review](#7319 (comment)) passed for head `617cbc1d62` and base `d3162e3422`; independent human sensitive-path review remains outstanding. - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Documentation Writer Review - [x] Documentation writer subagent reviewed the completed changes - Result: `docs-updated` - Evidence: Reviewed `docs/get-started/prerequisites.mdx`, `docs/manage-sandboxes/uninstall-nemoclaw.mdx`, `docs/reference/architecture.mdx`, `docs/reference/commands.mdx`, `docs/reference/platform-support.mdx`, and `docs/reference/troubleshooting.mdx` at PR SHA `617cbc1d6` against base SHA `d3162e342`. Verified the complete exact-head/base diff, terminology, product-scope boundaries, lifecycle and uninstall accuracy, recovery commands, and code-sample presentation against `WRITING.md` and `docs/CONTRIBUTING.md`; the readiness merge resolution preserves supplied environment input plus main’s Node 25 SNI behavior; `git diff --check` passed. - Agent: Codex Desktop documentation-writer subagent `/root/pr7319_docs_review_118571` <!-- docs-review-head-sha: 617cbc1 --> <!-- docs-review-agents-blob-sha: be20a09 --> ## DGX Station Hardware Evidence Not applicable; `scripts/prepare-dgx-station-host.sh` is unchanged. - [ ] Tested on DGX Station - Tested commit: - Station profile/scenario: - Result: - Supporting evidence: ## Verification - [x] PR description includes a `Signed-off-by:` line and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — 183 changed CLI tests; 36 changed E2E-support tests; 116 changed integration tests with 1 skipped; 40 installer-integration tests with 1 skipped. Follow-up behavior head `d07a0576b`: 8 authority tests passed; the macOS E2E command passed 9 tests with 2 environment-skipped. Credential-sanitization fix: E2E-support passed 1,595 tests with 12 skipped, and the focused live test collected successfully without executing credentialed actions. Exact refreshed head `33bb483259`: gateway-service runtime tests passed 21/21, installer service tests passed 9/9, polling-helper tests passed 3/3, sandbox-provisioning tests passed 62/62, the live test collected successfully, test-size and CLI type checks passed, the documentation build passed, and the complete canonical-base diff-aware hook gate passed. Exact head `d5e9e2d916`: all 8 GPU rollback tests passed with deterministic terminal-phase fixtures. Exact refreshed head `2788106318`: 82 focused CLI tests and 68 provisioning/uninstall integration tests passed, the documentation build passed, and normal pre-commit and commit-message hooks passed. Exact head `ea29c8b28b`: all 7 gateway-service uninstall tests passed after the current-main fixture update, and normal pre-commit and commit-message hooks passed. Exact refreshed head `da79a35c73`: 45 CLI recovery/service tests and 10 process-recovery integration tests passed. Exact refreshed head `b0e9c86ceb`: 133 focused Perl-runtime, sandbox-provisioning, runner, and workflow-boundary tests passed outside the restricted sandbox; the canonical-base pre-commit, commit-message, and pre-push hook suites passed. Exact head `9a3148c0aa`: 20 focused lifecycle/E2E-support tests passed after formatter output, staged pre-commit/security hooks passed, canonical-base pre-push checks passed, and the docs build passed. Exact refreshed head `ed20dfd741`: 49 focused lifecycle and E2E scorecard tests passed; canonical-base pre-commit/security, commit-message, and pre-push hooks passed; the docs build passed. Exact refreshed head `34fbcfb4ad`: 182 focused service, lifecycle, installer, and E2E scorecard tests passed outside the restricted sandbox; canonical-base pre-commit/security, commit-message, and pre-push hooks passed; the docs build passed. Exact refreshed head `611b8fe05f`: the expanded service, lifecycle, installer, Hermes, and workflow suite passed 259 tests with 12 expected skips; canonical-base pre-commit/security, commit-message, and pre-push hooks passed; the docs build passed. Exact refreshed head `0a69b289ac`: the expanded service, lifecycle, installer, Hermes, and workflow suite passed 261 tests with 12 expected skips; canonical-base pre-commit/security, commit-message, and pre-push hooks passed; the docs build passed. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: not run locally; the required full CI and exact-pair E2E gates are being monitored. - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — passed with 0 errors and 2 existing Fern warnings. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) — not applicable; this PR changes existing pages. --- Signed-off-by: San Dang <sdang@nvidia.com> --------- Signed-off-by: San Dang <sdang@nvidia.com> Signed-off-by: Senthil Ravichandran <senthilr@nvidia.com> Co-authored-by: cjagwani <cjagwani@nvidia.com> Co-authored-by: Senthil Ravichandran <senthilr@nvidia.com>
This was referenced Jul 26, 2026
This was referenced Jul 27, 2026
miyoungc
pushed a commit
that referenced
this pull request
Jul 29, 2026
<!-- markdownlint-disable MD041 --> ## Summary This follow-up publishes the OpenShell gateway lifecycle authority and Enterprise Readiness pages in the OpenClaw, Hermes, and Deep Agents guide variants. It also makes intentional partial publication explicit in source frontmatter and fails the docs build when navigation and source scope differ. ## Related Issue Follow-up to #6576 and #7246. ## Changes - #7246 -> `docs/deployment/gateway-lifecycle-authority.mdx`: Publishes the host-side OpenShell gateway lifecycle contract for every applicable guide variant and distinguishes it from an in-sandbox agent gateway. - Publishes `docs/reference/enterprise-readiness.mdx` for LangChain Deep Agents Code and describes the runtime-specific dashboard, observability, and agent gateway boundaries. - Adds exact `agent-variants` declarations to 42 intentionally partial source pages. The docs generator compares these declarations with `docs/index.yml` because navigation alone cannot distinguish an omission from an intentional subset. - Updates Miyoung’s daily documentation-engineering workflow and its supporting instruction surfaces so guide variant scope is derived from implementation, tests, or accepted product scope. - Adds focused tests for missing, mismatched, and matching declarations and for all-variant OpenShell gateway routes. ### Change footprint This PR changes 52 files, but most of that count is the baseline required by the new validation: - **42 files:** Add one `agent-variants` frontmatter line to existing pages whose publication is intentionally limited to a subset of the OpenClaw, Hermes, and Deep Agents guides. Their documentation content does not change. - **3 files:** Correct the user-facing publication and wording for the OpenShell gateway lifecycle and Enterprise Readiness pages: `docs/deployment/gateway-lifecycle-authority.mdx`, `docs/reference/enterprise-readiness.mdx`, and `docs/index.yml`. - **4 files:** Update Miyoung’s documentation-engineering workflow and its instruction surfaces: `.agents/skills/nemoclaw-contributor-update-docs/SKILL.md`, `docs/AGENTS.md`, `docs/CONTRIBUTING.md`, and `docs/resources/engineer-agentic-documentation.mdx`. - **3 files:** Add executable validation and focused tests: `scripts/sync-agent-variant-docs.mts`, `test/sync-agent-variant-docs.test.ts`, and `test/check-docs-published-routes.test.ts`. ### Miyoung’s documentation-engineering workflow Miyoung’s documentation-engineering workflow is not a separate bot, service, or scheduled GitHub workflow. It is the repository-owned `nemoclaw-contributor-update-docs` skill that she runs daily with Codex Desktop. Before this PR, the skill already knew how to render host CLI names for all three guide variants, but its new-page rule only told the documentation engineer to add the “appropriate navigation entry.” It did not require an explicit applicability decision or a source declaration for an intentional subset. Separately, the generator classified a page as shared by intersecting only the OpenClaw and Hermes navigation, and its guard applied only to pages containing the `$$nemoclaw` placeholder. As a result, a generic page with literal `nemoclaw` commands could be added only to the OpenClaw navigation and still pass the documentation build. This PR changes the workflow at each relevant layer: - `.agents/skills/nemoclaw-contributor-update-docs/SKILL.md`: Requires the daily documentation scan to determine applicability from implementation, tests, or accepted product scope; publish a page in every applicable guide variant; and declare an intentional subset with `agent-variants`. - `docs/AGENTS.md`: Gives the same rule to agents while they work under `docs/`. - `docs/CONTRIBUTING.md`: Makes the applicability decision and source declaration part of the contributor contract. - `docs/resources/engineer-agentic-documentation.mdx`: Updates the public description of the documentation engine so it no longer says that navigation alone defines variant membership. - `scripts/sync-agent-variant-docs.mts`: Enforces the rule by comparing each source declaration with its actual OpenClaw, Hermes, and Deep Agents navigation membership during the documentation build. There is no separate scheduler to adjust. The documentation-writer receipt continues to verify that review happened on the current head; the new generator check supplies the missing publication-scope control. ## Type of Change - [ ] Code change (feature, bug fix, or refactor) - [x] Code change with doc updates - [ ] Doc only (prose changes, no code sample modifications) - [ ] Doc only (includes code sample changes) ## Quality Gates - [x] Tests added or updated for changed behavior - [ ] Existing tests cover changed behavior — justification: - [ ] Tests not applicable — justification: - [x] Docs updated for user-facing behavior changes - [ ] Docs not applicable — justification: - [x] Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging) - [x] Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Frontmatter-only scope declarations under sensitive documentation paths were included in the independent implementation and navigation scope audit. No security behavior or security claim changed. - [ ] Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: ## Documentation Writer Review - [x] Documentation writer subagent reviewed the completed changes - Result: `docs-updated` - Evidence: Reviewed `.agents/skills/nemoclaw-contributor-update-docs/SKILL.md`, `docs/AGENTS.md`, `docs/CONTRIBUTING.md`, `docs/index.yml`, the 45 changed MDX source pages, the generator, and the focused tests. The review covered the writing rules, documentation style, guide variant terminology, gateway boundaries, rendered commands, and declared publication scope. Focused tests passed 36/36, and `npm run docs` completed with 0 errors and 2 pre-existing Fern warnings. - Agent: Codex Desktop <!-- docs-review-head-sha: f8bdaba --> <!-- docs-review-agents-blob-sha: d48a7cb --> ## 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 - [x] PR description includes a `Signed-off-by:` line and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: `npm exec -- vitest run test/sync-agent-variant-docs.test.ts test/check-docs-published-routes.test.ts` passed 36/36 tests at `f8bdabacc`. - [ ] Applicable broad gate passed — `npm test` for broad runtime/test-harness changes; `npm run check` for repo-wide validation/coverage changes — command/result: Not applicable; this change does not alter broad runtime behavior or the test harness. - [x] Quality Gates section completed with required justifications or waivers - [x] No secrets, API keys, or credentials committed - [ ] `npm run docs` builds without warnings (doc changes only) — result: 0 errors and 2 pre-existing Fern warnings. - [x] Doc pages follow the [style guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md) (doc changes only) - [ ] New doc pages include SPDX header and frontmatter (new pages only) — not applicable; this PR adds no source page. --- Signed-off-by: Julie Yaunches <jyaunches@nvidia.com> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added clearer guidance for identifying which agent variants each guide supports. * Improved documentation metadata and navigation so OpenClaw, Hermes, and Deep Agents guides appear in the appropriate sections. * Clarified gateway lifecycle authority, enterprise readiness, and related deployment guidance. * Updated command examples and troubleshooting instructions for gateway management. * **Bug Fixes** * Ensured shared documentation is published consistently across applicable guide variants. * Added validation to detect missing, mismatched, or broken variant-specific documentation routes. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
23 tasks
This was referenced Aug 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
External systemd supervisors can now remain the sole OpenShell gateway lifecycle authority while NemoClaw validates and attaches to their exact endpoint. The authority is persisted across onboarding resume, and every preflight, start, recovery, attachment, stop, final-sandbox cleanup, and uninstall path fails closed instead of creating or tearing down the wrong gateway.
Thank you to @souvikDevloper for the original contribution in #6842, and to @apurvvkumaria for the follow-up work. The underlying onboarding architecture shifted to per-gateway bindings and versioned checkpoints while that PR was open, so this needed a fresh implementation. Its central ideas and structure remain here: an explicit authority contract, pure ownership evaluation, host attestation, and composed lifecycle guards.
Related Issue
Refs #6576
Supersedes #6842
Changes
nemoclaw status,status --json, andnemoclaw debug, without the external state directory or credential values.gateway destroyfor them.Type of Change
Quality Gates
Documentation Writer Review
docs-updatedbcbbef70cadds only an empty signed CI-retry commit. Its tree and effective PR documentation diff are identical to reviewed head1bd90ae67.git diff --checkpassed.Verification
Signed-off-by:line and every commit appears asVerifiedin GitHubpre-commit,commit-msg, andpre-pushhooks passed, ornpm run check:diffpassed when hooks were skipped or unavailablenpm run check:diff, and normal commit/pre-push hooks passed.bcbbef70con current base46ecb8677; final coordination passed.npm run docsbuilds without warnings (doc changes only) — passed with 0 errors and 2 pre-existing Fern warningsSigned-off-by: Julie Yaunches jyaunches@nvidia.com
Signed-off-by: Prekshi Vyas prekshiv@nvidia.com
Summary by CodeRabbit
status/debugto display redacted gateway authority details.