fix(inference): reap managed vLLM processes

[senthilr-nv]

Summary

Managed vLLM containers now use Docker's init process so child processes are reaped and signals are forwarded during restart. This restores clean docker restart behavior while preserving the existing unless-stopped policy and all model, GPU, network, and credential arguments.

Related Issue

Fixes #7219

Changes

• Add --init to the shared managed-vLLM docker run argument builder.
• Preserve the existing --restart unless-stopped lifecycle contract and profile-specific run flags.
• Add focused regression coverage for both lifecycle flags and update exact generated-argv assertions.

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: this restores the already-documented managed-vLLM restart behavior without changing commands, configuration, or workflow; documentation review found no source-page update necessary.
• 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: pending maintainer review.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project cli src/lib/inference/vllm.test.ts (59 passed)
• Applicable broad gate passed — not applicable to this two-file Docker-argv correction; focused tests, npm run build:cli, and npm run typecheck:cli passed.
• 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)

Physical Reproduction

The restart failure was independently reproduced on two physical DGX Station GB300 systems. The v0.0.88 clean installation and inference/chat/tool checks passed, but docker restart nemoclaw-vllm timed out with Docker reporting a zombie PID and recommending --init; starting the same stopped container recovered inference.

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved managed vLLM container reliability by enabling proper signal forwarding and child-process cleanup.
  • Preserved automatic container restart behavior when the service stops unexpectedly.
• Tests
  • Updated vLLM Docker run argument assertions to reflect the new --init flag behavior, including restart-related cases.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 56238288-b6ed-470a-ac23-e6e46a48608e

📥 Commits

Reviewing files that changed from the base of the PR and between a154308 and c7c41ae.

📒 Files selected for processing (2)

• src/lib/inference/vllm.test.ts
• src/lib/inference/vllm.ts

---

📝 Walkthrough

Walkthrough

The managed vLLM Docker command now includes --init alongside the existing restart policy. Documentation and tests cover signal handling, child-process reaping, argument ordering, and credential isolation.

Changes

vLLM container lifecycle

Layer / File(s)	Summary
Add Docker init to vLLM launch src/lib/inference/vllm.ts	buildVllmRunArgs adds Docker’s --init flag, with documentation describing signal forwarding and child-process reaping.
Update Docker argument coverage src/lib/inference/vllm.test.ts	Tests verify --init in profile, restart, and Hugging Face token argument scenarios while retaining restart and credential expectations.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#6523: Both changes update managed vLLM Docker argv construction and its exact argument-order tests.
• NVIDIA/NemoClaw#6771: Both changes modify managed vLLM Docker launch arguments and related test expectations.

Suggested labels: area: local-models

Suggested reviewers: apurvvkumaria, ericksoa

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding lifecycle handling for managed vLLM containers.
Linked Issues check	✅ Passed	The code and tests add Docker --init to managed vLLM runs and keep restart policy and other run flags unchanged.
Out of Scope Changes check	✅ Passed	The changes stay focused on vLLM container lifecycle behavior and regression tests, with no unrelated scope added.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high 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 · high 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: inference-routing, network-policy

1 optional E2E recommendation

• ubuntu-repo-docker-post-reboot-recovery

Workflow run details

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

[senthilr-nv]

Physical DGX Station verification: PASS

Tested exact PR head a154308859509f324b4f367a611b0934d9dbf498 with golden-path harness 2c04cf7 on a GB300 Station running generic Ubuntu 24.04 ARM64.

• Prepared-host warm install selected the true product default: OpenClaw 2026.6.10 + nvidia/nemotron-3-ultra-550b-a55b.
• Install completed successfully in 31m42.7s; model-cache growth was 0 bytes.
• Live container inspection confirmed Init=true and RestartPolicy=unless-stopped.
• docker restart nemoclaw-vllm returned successfully. The prior v0.0.88 container had reproduced the cleanup/restart hang on this same host.
• The same container/image and boot identity were preserved across restart.
• Restart-to-ready: 1848s for Ultra.
• Post-restart direct vLLM chat: DIRECT_VLLM_OK.
• Post-restart OpenClaw exact response: STATION_CHAT_OK.
• Post-restart host-evaluated tool artifact: STATION_TOOL_OK, expected total 42, input hash unchanged.
• GB300 ECC remained corrected=0, uncorrected=0 throughout.
• Sealed postflight and agent smoke both passed.

Scope note: this is warm prepared-host lifecycle verification, not a clean-host qualification. An anonymous Hugging Face metadata request received a non-blocking 429 after cached weights were already local; vLLM continued from cache and all readiness and functional checks passed. No new product or harness blocker was found.

[senthilr-nv]

Rebase verification update:

PR #7221 is now rebased onto current main (821aa06de) at head 4ed9f2b7e87c6bc28d19228296b63dd6f83c752a.

The rebased tree is identical to the prior branch update and the PR diff is unchanged: only src/lib/inference/vllm.ts and src/lib/inference/vllm.test.ts. The intervening Station preparation changes from #7223 and #7237 do not overlap the managed vLLM launch path.

Post-rebase verification:

• src/lib/inference/vllm.test.ts: 59/59 passed.
• Diff-scoped pre-commit, commitlint, pre-push, repository checks, secret scan, and CLI TypeScript checks passed.
• Commit is signed and GitHub reports verified=true.

The physical result above was run on the prior exact head a15430885; because this rebase changes only ancestry and adds non-overlapping upstream commits, no second physical lifecycle run was performed.