fix(onboard): treat refused gateway status as stale

[apurvvkumaria]

Summary

Re-publishes the reviewed #7143 change set on a trusted NVIDIA branch so the required protected E2E jobs can execute. It captures stderr from failed OpenShell status probes and distinguishes concrete connection failures from authentication, configuration, TLS, and CLI errors before deciding that a gateway is stale. This supersedes #7143 solely because the fork security boundary prevented its required E2E jobs from running.

Related Issue

Fixes #7087

Changes

• Keep runner.runCapture stdout-only by default while allowing the bounded gateway status probe to opt into stderr capture.
• Mark the selected gateway stale only for concrete connection failures and avoid destructive cleanup for unrelated status errors.
• Preserve the reviewed handler transition and add regression coverage for stderr capture, false positives, status variants, snapshot propagation, and gateway restart behavior.
• Preserve HwangJohn's original contribution through Co-authored-by trailers, including the current-main sync commit.

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: no user-facing command, flag, configuration, output format, or procedure changes; this only fixes internal gateway reuse classification.
• 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: exact reviewed change set approved on fix(onboard): treat refused gateway status as stale #7143 (review); the replacement preserves that net diff while syncing current main mechanically.
• 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: no-docs-needed
• Evidence: The change corrects internal gateway-state classification and matches the existing documented onboarding behavior. It adds no command, flag, configuration, output format, or user procedure; no docs/ paths need changing. The current-main topper leaves the effective eight-file product patch byte-identical to the independently reviewed patch (SHA-256 6accec058acd136fc90f773c40473b669e4e03de8734e7ee4d571590fc4ee2b0).
• Agent: Codex Desktop

Verification

• PR description includes a Signed-off-by: line and every published commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or equivalent targeted validation passed when hooks were unavailable
• Targeted behavior tests pass for the current change set — exact head 280efd274: npx vitest run --project cli src/lib/onboard/gateway-reuse.test.ts src/lib/onboard/machine/handlers/gateway.test.ts src/lib/runner-argv.test.ts (61 tests passed); npx vitest run --project integration test/gateway-state.test.ts (67 tests passed)
• CLI build and type-check pass — npm run build:cli; npm run typecheck:cli
• Applicable broad gate passed — not applicable; the focused runner and onboarding behavior is covered by the targeted CLI and integration suites above.
• 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)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved gateway reuse detection by capturing and interpreting both stdout and stderr from OpenShell status (including connection refusals and authentication-related failures).
  • Gateways with connection-related failures are now classified as stale and restarted when appropriate.
  • Gateways with non-connection status errors are now classified as missing instead of stale.
  • Refined gateway “connected”/“disconnected” detection using updated status-error patterns (OpenShell v0.0.85).
• Tests
  • Expanded snapshot, scenario, and fixture coverage for stderr-inclusive output and revised stale/missing classification behavior.

[coderabbitai]

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

Gateway status capture now includes stderr, enabling connection failures to classify as stale and other status errors as missing. Runner capture, gateway reuse logic, onboarding handling, and tests are updated.

Changes

Gateway reuse classification

Layer / File(s)	Summary
Capture status stderr src/lib/runner.ts, src/lib/runner-argv.test.ts, src/lib/onboard/gateway-reuse.ts, src/lib/onboard/gateway-reuse.test.ts	runCapture supports opt-in stderr capture for failed commands, and gateway status probing enables it with coverage for combined output.
Classify gateway status errors src/lib/state/gateway.ts, test/gateway-state.test.ts, test/fixtures/openshell-status-errors-v0.0.85.json	Connectivity and reuse-state logic distinguish transport failures from authentication and other status errors, producing stale or missing as appropriate.
Apply stale reuse state during onboarding src/lib/onboard/machine/handlers/gateway.test.ts	Onboarding coverage verifies that a stale gateway is started without invoking skip or legacy-retirement paths.

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

Sequence Diagram(s)

sequenceDiagram
  participant Onboarding
  participant GatewayReuseHelpers
  participant OpenShell
  participant GatewayState
  Onboarding->>GatewayReuseHelpers: Request gateway reuse snapshot
  GatewayReuseHelpers->>OpenShell: Capture status with stderr
  OpenShell-->>GatewayReuseHelpers: Return status output
  GatewayReuseHelpers->>GatewayState: Classify gateway status
  GatewayState-->>Onboarding: Return stale or missing reuse state
  Onboarding->>OpenShell: Start stale gateway

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7143: Updates gateway reuse probing and classification for stderr-based connection failures.

Suggested reviewers: cv, prekshivyas

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes align with #7087 by preserving gateway reuse behavior and adding stale-handling coverage for concrete connection failures.
Out of Scope Changes check	✅ Passed	The additional stderr capture and status parsing changes support the gateway reuse fix and do not appear unrelated.
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 clearly matches the main change: classifying refused gateway status as stale during onboarding.

✨ 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 codex/7087-gateway-reuse-e2e-v3

---

_{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 fbe7af2 in the codex/7087-gateway-r... branch remains at 96%, unchanged from commit 9171d79 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit fbe7af2 in the codex/7087-gateway-r... branch remains at 80%, unchanged from commit 9171d79 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 9171d79	codex/7087-gateway-r... fbe7af2	+/-
src/lib/inferen...time-context.ts	93%	87%	-6%
src/lib/state/m...-acquisition.ts	89%	86%	-3%
src/lib/state/gateway.ts	96%	96%	0%
src/lib/adapter.../auth-config.ts	96%	96%	0%
src/lib/inferen...lama-version.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/runner.ts	77%	78%	+1%
src/lib/inferen...del-registry.ts	97%	100%	+3%

---

_{Updated July 25, 2026 05:20 UTC}

[coderabbitai]

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/state/gateway.ts`:
- Around line 128-145: Update the connection-lifecycle detection logic around
the status classification to match every connection-related phrase, including
“Connection refused” and the existing alternatives, against statusError rather
than clean output, while requiring statusError to be non-empty. Preserve the
current transport/reset/aborted/closed checks and add the regression test
covering a healthy status whose diagnostic mentions “Connection refused” so it
is not marked stale.

🪄 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: 36e62a3a-0e51-4f57-86ef-aabbd1679cf4

📥 Commits

Reviewing files that changed from the base of the PR and between 4deebcf and 368cb07.

📒 Files selected for processing (7)

• src/lib/onboard/gateway-reuse.test.ts
• src/lib/onboard/gateway-reuse.ts
• src/lib/onboard/machine/handlers/gateway.test.ts
• src/lib/runner-argv.test.ts
• src/lib/runner.ts
• src/lib/state/gateway.ts
• test/gateway-state.test.ts

[github-actions]

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): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

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, cloud-onboard

1 optional E2E recommendation

• double-onboard

Workflow run details

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

[apurvvkumaria]

Exact-head maintainer audit on d8ac50a: opt-in stderr capture is stripped from spawn options, remains stdout-only by default, and is used only by the bounded gateway status probe. Stale classification requires both selected-gateway identity and a concrete connection failure on an actual status-error line; auth, configuration, TLS, CLI, and healthy diagnostic text remain non-destructive. Focused CLI tests pass 53/53, integration tests pass 130/130, CLI type-check and diff check pass, both commits are GitHub Verified with DCO and HwangJohn credit, all CI/advisors/protected E2E are green, and no review thread remains unresolved. No blocking security or correctness issue found. Independent review requested from @cv because the PR is authored by the current maintainer account.

[apurvvkumaria]

Independent comparator audit confirms this is the canonical #7087 implementation over #7143. Exact head d8ac50af5 scopes every connection-failure phrase to the parsed status-error suffix, preserves healthy informational diagnostics, and adds the missing Connection refused paired regression. All checks—including protected E2E—are green, all commits are Verified/DCO-compliant, there are zero unresolved threads, and HwangJohn is credited as co-author. No code or label change is needed; this now only needs the requested independent human approval.

[apurvvkumaria]

Current-main refresh is now on exact head 2c7ec9a4a5a3ef0ed0c9fd1f8c67819084fb010e.

• Signed DCO merge commit, GitHub Verified.
• Parents are prior PR head d8ac50af5c4836cf1b59b9d8f829b1e6a27c6147 and current main 3c4ea5a1e3c37ae6688399b823258e1c31790fd2.
• The refresh was conflict-free; current main and the PR had no changed-file overlap.
• The PR-relative patch remains exactly seven files with 228 additions and 9 deletions; no contributor intent or semantics changed.
• Focused validation passed: 53 CLI tests, 66 gateway-state integration tests, CLI typecheck, source-shape, title checks, diff check, and docs build (0 errors; 2 existing warnings).
• Original contributor HwangJohn remains credited.

Fresh exact-head CI and automated review are running. No release label was changed.

[apurvvkumaria]

Pushed 285eab641de6c1d5c9052d7f43fa0b5aa78c6994 to close the current-head runCapture contract gap.

• Ignored failures once again return an empty string by default, even when the failed process wrote stdout.
• includeStderr: true remains the explicit opt-in for combined stdout/raw-stderr capture.
• Added the missing stdout-on-failure regression test.
• The commit is signed, DCO-compliant, and credits HwangJohn as co-author.

Validation passed:

• runner CLI tests: 34/34
• runner integration tests: 64/64
• gateway CLI tests: 20/20
• gateway integration tests: 66/66
• CLI build and typecheck
• title/source-shape checks, full commit hooks, repository checks, gitleaks, and commitlint
• security review across the nine maintainer categories; no blocker found
• documentation audit: no user-facing documentation change required

Fresh exact-head CI and advisor checks are now running.

[apurvvkumaria]

Addressed the exact-head advisor PRA-1 in Verified commit ba440cd.

• Documented the OpenShell v0.0.85 status-error compatibility boundary and its removal condition next to the parser.
• Added a checked-in producer fixture covering connection refusal and a non-lifecycle authentication error.
• Added classifier coverage proving refusal remains stale while the unrelated error remains missing.

Validation: gateway-state integration tests 67/67 passed; CLI typecheck and scoped hooks passed. This follow-up changes no runtime behavior. HwangJohn remains credited as co-author.

[coderabbitai]

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 `@test/fixtures/openshell-status-errors-v0.0.85.json`:
- Around line 1-7: Add the repository’s standard SPDX text as a top-level
$comment field in the JSON fixture, placing it alongside the existing metadata
fields while preserving valid JSON and all current fixture values.

🪄 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: 0cdb76cc-6e6b-47b9-a1d5-d59e55d4ed6d

📥 Commits

Reviewing files that changed from the base of the PR and between 285eab6 and ba440cd.

📒 Files selected for processing (3)

• src/lib/state/gateway.ts
• test/fixtures/openshell-status-errors-v0.0.85.json
• test/gateway-state.test.ts

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

• src/lib/state/gateway.ts

[apurvvkumaria]

Addressed the canonical advisor warning in signed commit ede02988a with a handler-level retry regression: the first refused-status gateway start fails without completing, skipping, or retiring the gateway step; the second invocation succeeds with exactly one completion and the expected transition. Validation: focused handler 24/24, full targeted CLI set 61/61, CLI type-check, and all file-scoped prek hooks passed. The red Nemotron lane itself was a model protocol failure (pr_review_update_ledger was not committed), not a code/test failure.

[ericksoa]

Approved at exact head 1c09d95 after full diff and nine-category security review. Targeted CLI and integration suites, build/typecheck/check:diff, all current CI checks, selected onboard-repair/onboard-resume E2E, advisor ledger, resolved review threads, DCO, commit verification, and current-base checks are green.