[WIP] Summary

Fixes #32116.

When engine core startup times out (e.g. during long deep_gemm warmup), API server workers die with TimeoutError but the launcher's wait_for_engine_startup() had no matching deadline — it blocked indefinitely, leaving engine cores and their GPU-holding VLLM::Worker subprocesses orphaned. Users could not reclaim GPU memory without killing processes manually.

This PR makes two changes to vllm/v1/engine/utils.py:

• Add a startup deadline to wait_for_engine_startup() — the function now raises TimeoutError after VLLM_ENGINE_READY_TIMEOUT_S elapses, with an actionable message telling users how to extend the window.
• Wrap launch_core_engines() yield + wait in try/except BaseException — on any failure (timeout, SIGINT, engine crash mid-handshake), local_engine_manager.shutdown() and coordinator.shutdown() are called explicitly before re-raising. Previously, cleanup fell to a weakref.finalize safety net with a hardcoded 5s grace and no log output.

Not a duplicate of existing PRs

• [Bugfix] Kill orphan EngineCore/WorkerProc via prctl(PR_SET_PDEATHSIG) #34816 and [V1][Bugfix] Reap EngineCore on parent death (#19849) #40935 address orphan cleanup when the parent process dies abnormally (SIGKILL, OOM-kill) via OS-level mechanisms (prctl(PR_SET_PDEATHSIG), kqueue). Those are complementary to this fix.
• This PR fixes the case where the parent is still alive but fails to call shutdown() when startup times out or is interrupted — a different failure path in the same launch_core_engines() generator.

Test plan

Unit tests (new file: tests/v1/shutdown/test_startup_timeout_cleanup.py)

Three tests exercising wait_for_engine_startup() in isolation (no GPU required):

• test_wait_for_engine_startup_raises_timeout_on_silent_engine — verifies TimeoutError fires promptly when no HELLO arrives
• test_wait_for_engine_startup_timeout_message_is_informative — verifies the error message mentions VLLM_ENGINE_READY_TIMEOUT_S
• test_wait_for_engine_startup_succeeds_on_hello_ready — happy-path regression test

.venv/bin/python -m pytest tests/v1/shutdown/test_startup_timeout_cleanup.py -v
# Result: 3/3 passed

Linters

pre-commit run --files vllm/v1/engine/utils.py tests/v1/shutdown/test_startup_timeout_cleanup.py
# Result: all hooks passed (ruff-check, ruff-format, mypy, typos)

Manual GPU verification (2×A40, Qwen3-30B-A3B, DP=2)

AI-assisted contribution disclosure

This PR was developed with assistance from Claude (Anthropic). All code has been reviewed, understood, and tested by the human submitter. Commit includes Co-authored-by: Claude trailer.