Skip to content

[controllers] fix: surface cuda mps runtime failures - #133

Merged
Wangmerlyn merged 2 commits into
mainfrom
codex/cuda-mps-runtime-health-status
Jun 28, 2026
Merged

[controllers] fix: surface cuda mps runtime failures#133
Wangmerlyn merged 2 commits into
mainfrom
codex/cuda-mps-runtime-health-status

Conversation

@Wangmerlyn

@Wangmerlyn Wangmerlyn commented Jun 28, 2026

Copy link
Copy Markdown
Owner

Summary

  • retain CUDA/MPS post-start worker failures through allocation_status(), including non-OOM allocation and steady-state RuntimeError failures
  • preserve recoverable OOM retry/backoff behavior with explicit no-GPU regression tests
  • clean dead runtime-failed CUDA/MPS workers during release and document the runtime-health contract in AGENTS.md and docs/plans

Verification

  • PYTHONPATH=$PWD/src pytest tests/cuda_controller/test_throttle.py::test_cuda_records_post_start_runtime_error_as_failure tests/cuda_controller/test_throttle.py::test_cuda_records_post_start_allocation_runtime_error_as_failure tests/cuda_controller/test_throttle.py::test_cuda_retries_post_start_allocation_oom_without_failure tests/cuda_controller/test_throttle.py::test_cuda_retries_steady_state_oom_without_failure tests/macm_controller/test_macm_backoff.py::test_macm_records_post_start_runtime_error_as_failure tests/macm_controller/test_macm_backoff.py::test_macm_records_post_start_allocation_runtime_error_as_failure tests/macm_controller/test_macm_backoff.py::test_macm_retries_post_start_allocation_oom_without_failure tests/macm_controller/test_macm_backoff.py::test_macm_retries_steady_state_oom_without_failure tests/single_gpu_controller/test_release_contract.py::test_release_cleans_dead_runtime_failed_cuda_mps_worker tests/global_controller/global_keep_test.py::test_global_runtime_error_preserves_rank_prefixed_child_failure -q (13 passed)
  • PYTHONPATH=$PWD/src pytest tests/cuda_controller tests/macm_controller tests/single_gpu_controller/test_release_contract.py tests/global_controller/global_keep_test.py -q (58 passed, 10 skipped)
  • PYTHONPATH=$PWD/src pytest tests -q (558 passed, 11 skipped)
  • PYTHONPATH=$PWD/src mkdocs build (passed; existing Material notice and unnav'd plan-page list)
  • pre-commit run --all-files (passed)
  • git diff --check (passed)

Local Review

  • Spec review: no P0/P1/P2/P3 findings; OOM retry gap verified closed
  • Quality review: no P0/P1/P2/P3 findings; focused runtime-health shard passed read-only

Summary by CodeRabbit

  • New Features

    • Added runtime health reporting for CUDA and MPS GPU controllers so fatal post-start failures are now surfaced to the main service status.
    • Improved release handling to clear GPU cache and reset state when a controller has failed.
  • Bug Fixes

    • Kept out-of-memory situations on a retry path without marking the service as failed.
    • Preserved existing error details when a child controller reports a runtime failure.

@coderabbitai

coderabbitai Bot commented Jun 28, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@Wangmerlyn, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 42 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 97c36336-a654-4b8f-a6ff-f4ecdc13c359

📥 Commits

Reviewing files that changed from the base of the PR and between 0b152c4 and 057b57d.

📒 Files selected for processing (2)
  • docs/plans/cuda-mps-runtime-health-status.md
  • tests/macm_controller/test_macm_backoff.py
📝 Walkthrough

Walkthrough

Adds _failure_exc field and allocation_status() method to CudaGPUController and MacMGPUController. Fatal post-start worker failures are recorded in _failure_exc (non-OOM errors terminate the worker; OOM errors retry). release() treats a recorded failure as a cleanup trigger. Tests cover all new failure/retry paths and the global controller's rank-prefixed passthrough behavior.

Changes

CUDA/MPS Runtime Health Status

Layer / File(s) Summary
Controller _failure_exc field and allocation_status() contract
src/keep_gpu/single_gpu_controller/cuda_gpu_controller.py, src/keep_gpu/single_gpu_controller/macm_gpu_controller.py
Initializes _failure_exc = None in __init__ and keep(), adds public allocation_status() to both controllers, and extends release() to clear GPU cache and reset thread state when a recorded failure is present.
CudaGPUController._keep_loop failure recording
src/keep_gpu/single_gpu_controller/cuda_gpu_controller.py
Records exceptions into _failure_exc for missing stop-event, invalid VRAM config, non-OOM allocation/runtime errors, and unexpected steady-state exceptions; OOM errors continue to retry unchanged.
MacMGPUController._keep_loop failure recording
src/keep_gpu/single_gpu_controller/macm_gpu_controller.py
Records _failure_exc for missing stop-event, invalid vram_to_keep, non-OOM RuntimeError, and unexpected exceptions; "out of memory" RuntimeError clears MPS cache and retries.
CudaGPUController failure and retry tests
tests/cuda_controller/test_throttle.py
Adds _StopWaitForbidden helper and seven new tests covering post-start failure recording, OOM retry without failure, steady-state OOM, and invalid vram_to_keep=0 configuration.
MacMGPUController failure and retry tests
tests/macm_controller/test_macm_backoff.py
Adds _StopWaitForbidden helper and six new tests covering unexpected failure, RuntimeError recording, allocation errors, OOM allocation retry, and steady-state OOM retry via allocation_status().
release() contract and global passthrough tests
tests/single_gpu_controller/test_release_contract.py, tests/global_controller/global_keep_test.py
Adds parametrized release() test for dead runtime-failed workers across both controllers; adds global test verifying GlobalGPUController.runtime_error() preserves rank-prefixed child exceptions unchanged.
Architecture docs and implementation plan
AGENTS.md, docs/plans/cuda-mps-runtime-health-status.md
Updates AGENTS.md architecture boundaries for CUDA/MPS fatal failure handling; adds full plan document with goal, solution bullets, task checklist, follow-up items, and verification log.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • Wangmerlyn/KeepGPU#94: Modifies the same _keep_loop allocation paths in CUDA/MacM controllers (busy threshold deferral), overlapping with this PR's non-OOM vs OOM branching in the same code sections.
  • Wangmerlyn/KeepGPU#101: Modifies the CUDA controller keep()/_keep_loop() startup-failure path using startup_errors handshake, which this PR extends with _failure_exc post-start failure capture.
  • Wangmerlyn/KeepGPU#108: Implements GlobalGPUController.runtime_error() and the state="runtime_failed" plumbing that consumes the allocation_status() hook added in this PR.

Poem

🐇 Hoppity-hop through the GPU land,
Where fatal failures are caught by hand.
_failure_exc tucked safe in a field,
allocation_status() the truth revealed!
OOM? Just retry, no drama today—
The rabbit keeps VRAM from slipping away. 🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 11.54% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title is concise and accurately summarizes the main change: surfacing CUDA/MPS runtime failures from controllers.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/cuda-mps-runtime-health-status

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@gemini-code-assist gemini-code-assist 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.

Code Review

This pull request implements the propagation of fatal post-start CUDA and MPS worker failures to the service status via the allocation_status() hook. It introduces a _failure_exc attribute to track unexpected exceptions (excluding recoverable out-of-memory errors) and ensures that release() correctly cleans up resources for dead, failed workers. Extensive regression and unit tests have been added to verify these behaviors across both CUDA and MPS controllers. I have no further feedback to provide as there are no review comments to evaluate.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

@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.

🧹 Nitpick comments (1)
tests/macm_controller/test_macm_backoff.py (1)

104-290: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add the missing MPS invalid-config regression test.

MacMGPUController._keep_loop() now reports invalid vram_to_keep=... through allocation_status() when _num_elements <= 0, but this suite only covers worker/allocation failures and OOM retries. CUDA already has the parity test, so an MPS regression on that branch would currently slip through.

Suggested test shape
+def test_macm_records_invalid_post_start_num_elements_as_failure():
+    ctrl = MacMGPUController.__new__(MacMGPUController)
+    ctrl.rank = 0
+    ctrl.device = "mps"
+    ctrl.interval = 0.01
+    ctrl.busy_threshold = -1
+    ctrl.iterations = 1
+    ctrl.vram_to_keep = 0
+    ctrl._num_elements = 0
+    ctrl._failure_exc = None
+    ctrl._stop_evt = _StopWaitForbidden()
+
+    ctrl._keep_loop()
+
+    error = ctrl.allocation_status()
+    assert isinstance(error, RuntimeError)
+    assert str(error) == "rank 0: invalid vram_to_keep=0"

As per path instructions, "Behavior changes in single-GPU controllers must be kept in sync with related docs and tests."

🤖 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 `@tests/macm_controller/test_macm_backoff.py` around lines 104 - 290, Add a
regression test in the MacM backoff suite for the invalid configuration path in
MacMGPUController._keep_loop(). Create a controller with _num_elements set to 0
or below, run the loop, and assert allocation_status() returns a RuntimeError
whose message matches the new invalid vram_to_keep=... failure text. Use the
existing MacMGPUController setup pattern in the other tests to keep it
consistent with the MPS worker/allocation/OOM coverage.

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.

Nitpick comments:
In `@tests/macm_controller/test_macm_backoff.py`:
- Around line 104-290: Add a regression test in the MacM backoff suite for the
invalid configuration path in MacMGPUController._keep_loop(). Create a
controller with _num_elements set to 0 or below, run the loop, and assert
allocation_status() returns a RuntimeError whose message matches the new invalid
vram_to_keep=... failure text. Use the existing MacMGPUController setup pattern
in the other tests to keep it consistent with the MPS worker/allocation/OOM
coverage.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6ddac72e-5ab6-45fe-bf03-67245d00892c

📥 Commits

Reviewing files that changed from the base of the PR and between 5dfff6a and 0b152c4.

📒 Files selected for processing (8)
  • AGENTS.md
  • docs/plans/cuda-mps-runtime-health-status.md
  • src/keep_gpu/single_gpu_controller/cuda_gpu_controller.py
  • src/keep_gpu/single_gpu_controller/macm_gpu_controller.py
  • tests/cuda_controller/test_throttle.py
  • tests/global_controller/global_keep_test.py
  • tests/macm_controller/test_macm_backoff.py
  • tests/single_gpu_controller/test_release_contract.py

@Wangmerlyn

Copy link
Copy Markdown
Owner Author

Resolved CodeRabbit's MPS invalid-config coverage nitpick in follow-up commit 057b57d by adding test_macm_records_invalid_post_start_num_elements_as_failure, matching the existing CUDA invalid _num_elements coverage.

Follow-up verification after the change:

  • PYTHONPATH=$PWD/src pytest tests/macm_controller/test_macm_backoff.py::test_macm_records_invalid_post_start_num_elements_as_failure tests/cuda_controller/test_throttle.py::test_cuda_records_invalid_post_start_num_elements_without_startup_errors -q -> 2 passed
  • PYTHONPATH=$PWD/src pytest tests/cuda_controller tests/macm_controller tests/single_gpu_controller/test_release_contract.py tests/global_controller/global_keep_test.py -q -> 59 passed, 10 skipped
  • PYTHONPATH=$PWD/src pytest tests -q -> 559 passed, 11 skipped
  • PYTHONPATH=$PWD/src mkdocs build, pre-commit run --all-files, and git diff --check all passed.

@Wangmerlyn
Wangmerlyn merged commit f2e6008 into main Jun 28, 2026
5 checks passed
@Wangmerlyn
Wangmerlyn deleted the codex/cuda-mps-runtime-health-status branch June 28, 2026 21:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant