[Bugfix][HiSparse] Adopt GPU prefix copies after the hit's allocation

[MatthewBonanni]

Purpose

Fix an engine crash (Cannot get N free blocks from the pool) on a HiSparse host-prefix hit under GPU memory pressure. This is an alternative to #57457.

Closes #59440.

"Adopting" a GPU copy means a host-prefix hit points its page at a still-valid GPU copy of that host page (a GPU-side prefix-cache hit) instead of reading the page back from host.

A host-prefix hit re-pins free GPU copies of its pages so the prefix comes back GPU-resident. Admission counts those copies as free blocks, but adoption pinned them before the hit's own allocation (hot region and new pages), which could then run the pool dry.

#57457 fixes this by charging the pins at admission. That mixes host and GPU accounting in HiSparseSourceManager.get_num_blocks_to_allocate, and under pressure it defers a request that could run by reading its prefix from host, just to keep an optimization.

Changes

HiSparse-only (vllm/v1/hisparse/coordinator.py):

• Adopt after allocation. commit_computed_blocks records the pages to adopt, and update_residency (in cache_blocks, after allocate_new_blocks) adopts the copies that survived. The allocation always gets what admission counted, so no admission accounting is needed. A copy the allocation reuses is dropped by its reuse watcher and never adopted.
• Tail first. HiSparse releases a prefix's pages tail first, matching free_blocks' convention, so pressure trims a prefix from its end.

Replaying #57457's scenario (a resumed 3-page host prefix hit, free_blocks left in the pool):

free_blocks	main	#57457	this PR
5–6	rejected	rejected	rejected
7–8	crash	rejected	admitted, 0/3 copies
9	crash	rejected	admitted, 1/3
10	3/3	3/3	2/3
11+	3/3	3/3	3/3

Near the boundary this keeps fewer copies than #57457, because blocks freed after the copies are queued behind them. #59283, stacked on this PR, is an optional core change that restores 3/3 at 10.

Test Plan

• test_hisparse_prefix_hit_under_pressure_adopts_surviving_copies[7, 10]: exact adopted pages, and no block shared between adopted copies and fresh allocations. 7 fails without the adoption timing, and 10 without tail-first release.
• tests/v1/core/test_prefix_caching.py and tests/v1/core/test_kv_cache_utils.py, with CpuPlatform selected:

python cpu_pytest.py --confcutdir=tests/v1/core tests/v1/core/test_prefix_caching.py tests/v1/core/test_kv_cache_utils.py

Test Result

• Both new cases fail on main and pass with this PR.
• CPU (CpuPlatform): 295 passed. 8 errors are fixture 'caplog_vllm' not found, from running outside the top-level conftest, and are identical on main.
• H100, HiSparse unit tests across tests/v1 (-k hisparse): 156 passed.
• H100, test_prefix_caching.py + test_kv_cache_utils.py: 301 passed. The 2 failures (test_get_kv_cache_config_mamba_hybrid_sharing_pp_*) need 4 visible GPUs and fail identically on main with 1.
• H100, tests/v1/e2e/general/test_hisparse.py: fails with this PR alone (see the dependency note); with [Bugfix][HiSparse] Resolve MTP verification rows with a union residency kernel #59235 merged in, 2 passed in each of 2 runs.

AI assistance (Claude Code) was used for the investigation, implementation, tests, and this description.

🤖 Generated with Claude Code

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[LucasWilkinson]

LGTM thanks!

[MatthewBonanni]

/ci run

[github-actions]

✅ Triggered Buildkite CI #92209 for commit b9e969fceb50.

[MatthewBonanni]

/ci retry

[github-actions]

✅ Triggered Buildkite CI #92226 for commit 13e154219089, running 1 failed step(s) from Buildkite CI #92209.

[vllm-agent]

CI selector (shadow): 6 test steps (9 jobs) instead of 57 (73 jobs)

Shadow mode: this changes nothing about what CI runs. It shows what the evidence-based selector would pick for this PR, next to today's rules. How it works.

Feedback welcome: reply here if it would skip a step this change needs, or runs something unrelated.

steps (jobs)	Today's rules	Selector	Would skip	Would add
NVIDIA, CPU and others	57 (73)	6 (9)	52 (65)	1 (1)
AMD mirrors	50 (64)	5 (8)	46 (57)	1 (1)

Selector would run (6)

• e2e-core-1-gpu
• engine
• v1-core
• v1-executor-worker
• v1-kv-connectors ×4
• v1-others-cpu

Would skip (today's rules run them) (52)

• ascend-npu-test
• async-engine-inputs-utils-worker
• basic-correctness ×2
• basic-correctness-cpu-offload
• basic-correctness-cumem
• basic-correctness-prefetch-offload
• basic-correctness-sleep-mode
• basic-models-test-other-cpu
• basic-models-tests-initialization
• basic-models-tests-other
• benchmarks-cli-test
• cpu-language-generation-and-pooling-model-tests ×3
• cpu-multimodal-config
• cpu-params-env-tokenizers-parser
• cpu-reasoning-renderers
• cpu-tool-parsers
• e2e-core-large-memory
• e2e-scheduling-1-gpu
• entrypoints-integration-api-server ×4
• entrypoints-integration-api-server-generate
• entrypoints-integration-api-server-openai-chat_completion
• entrypoints-integration-api-server-openai-completion
• entrypoints-integration-llm
• entrypoints-integration-multimodal
• entrypoints-integration-pooling
• entrypoints-integration-responses-api
• entrypoints-integration-speech_to_text
• kernels-fla-ops-test-b200
• kernels-mhc-test-b200
• kernels-root-misc-test-b200
• language-models-tests-granite-l4-compatibility
• language-models-tests-hybrid ×2
• language-models-tests-standard
• metrics-tracing-2-gpus
• multi-modal-models-standard-1-qwen2
• multi-modal-models-standard-2-qwen3-gemma
• multi-modal-models-standard-3-llava-qwen2-vl
• multi-modal-models-standard-4-other-whisper
• multi-modal-processor ×4
• multi-modal-processor-cpu ×4
• pytorch-compilation-dynamic-shapes
• pytorch-compilation-passes-unit-tests
• pytorch-compilation-unit-tests
• pytorch-compilation-unit-tests-h100
• pytorch-fullgraph-cudagraph-l4-compatibility
• pytorch-fullgraph-test
• regression
• v1-kv-offload
• v1-logits-oracle
• v1-metrics-lmeval
• v1-sample
• v1-spec-decode

Would add (today's rules do not run them) (1)

• engine (code map)

AMD mirrors: would skip (46)

• async-engine-inputs-utils-worker
• basic-correctness ×2
• basic-correctness-cpu-offload
• basic-correctness-cumem
• basic-correctness-prefetch-offload
• basic-correctness-sleep-mode
• basic-models-test-other-cpu
• basic-models-tests-initialization
• basic-models-tests-other
• benchmarks-cli-test
• e2e-core-large-memory
• e2e-scheduling-1-gpu
• entrypoints-integration-api-server ×4
• entrypoints-integration-api-server-generate
• entrypoints-integration-api-server-openai-chat_completion
• entrypoints-integration-api-server-openai-completion
• entrypoints-integration-llm
• entrypoints-integration-multimodal
• entrypoints-integration-pooling
• entrypoints-integration-responses-api
• entrypoints-integration-speech_to_text
• kernels-fla-ops-test-b200
• kernels-mhc-test-b200
• kernels-root-misc-test-b200
• language-models-tests-granite-l4-compatibility
• language-models-tests-hybrid ×2
• language-models-tests-standard
• metrics-tracing-2-gpus
• multi-modal-models-standard-1-qwen2
• multi-modal-models-standard-2-qwen3-gemma
• multi-modal-models-standard-3-llava-qwen2-vl
• multi-modal-models-standard-4-other-whisper
• multi-modal-processor ×4
• multi-modal-processor-cpu ×4
• platform-tests
• pytorch-compilation-dynamic-shapes
• pytorch-compilation-passes-unit-tests
• pytorch-compilation-unit-tests
• pytorch-compilation-unit-tests-h100
• pytorch-fullgraph-test
• regression
• v1-kv-offload
• v1-logits-oracle
• v1-metrics-lmeval
• v1-sample
• v1-spec-decode

AMD mirrors: would add (1)

• engine (code map)

CI results (2026-09-30 19:56 UTC)

3 passed, 0 failed, 0 pending.

No failures to judge.

_{2 changed files · base 84f738f187 · head 3eb6cec22a · Python record: not used (/tmp/ci-infra-selector/buildkite/ci_selector/coverage-data/table.json.gz is table version 5, expected 7; re-merge it from the raw recordings) · kernel record: table 866fa13 (build 92059), map 866fa13 · not counted: 10 build steps, 5 A100 steps the generator no longer emits, 8 optional steps the selector would also run}